<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Beautiful Soup Documentation &mdash; Beautiful Soup 4.2.0 documentation</title>
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '4.2.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Beautiful Soup 4.2.0 documentation" href="index.html#" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li><a href="index.html#">Beautiful Soup 4.2.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="beautiful-soup-documentation">
<h1>Beautiful Soup Documentation<a class="headerlink" href="index.html#beautiful-soup-documentation" title="Permalink to this headline">¶</a></h1>
<img alt="&quot;The Fish-Footman began by producing from under his arm a great letter, nearly as large as himself.&quot;" class="align-right" src="_images/6.1.jpg" />
<p><a class="reference external" href="http://www.crummy.com/software/BeautifulSoup/">Beautiful Soup</a> is a
Python library for pulling data out of HTML and XML files. It works
with your favorite parser to provide idiomatic ways of navigating,
searching, and modifying the parse tree. It commonly saves programmers
hours or days of work.</p>
<p>These instructions illustrate all major features of Beautiful Soup 4,
with examples. I show you what the library is good for, how it works,
how to use it, how to make it do what you want, and what to do when it
violates your expectations.</p>
<p>The examples in this documentation should work the same way in Python
2.7 and Python 3.2.</p>
<p>You might be looking for the documentation for <a class="reference external" href="http://www.crummy.com/software/BeautifulSoup/bs3/documentation.html">Beautiful Soup 3</a>.
If so, you should know that Beautiful Soup 3 is no longer being
developed, and that Beautiful Soup 4 is recommended for all new
projects. If you want to learn about the differences between Beautiful
Soup 3 and Beautiful Soup 4, see <a class="reference internal" href="index.html#porting-code-to-bs4">Porting code to BS4</a>.</p>
<p>This documentation has been translated into other languages by
Beautiful Soup users:</p>
<ul class="simple">
<li><a class="reference external" href="index.zh.html">这篇文档当然还有中文版.</a></li>
<li>このページは日本語で利用できます(<a class="reference external" href="http://kondou.com/BS4/">外部リンク</a>)</li>
<li>이 문서는 한국어 번역도 가능합니다. (<a class="reference external" href="http://coreapython.hosting.paran.com/etc/beautifulsoup4.html">외부 링크</a>)</li>
</ul>
<div class="section" id="getting-help">
<h2>Getting help<a class="headerlink" href="index.html#getting-help" title="Permalink to this headline">¶</a></h2>
<p>If you have questions about Beautiful Soup, or run into problems,
<a class="reference external" href="https://groups.google.com/forum/?fromgroups#!forum/beautifulsoup">send mail to the discussion group</a>. If
your problem involves parsing an HTML document, be sure to mention
<a class="reference internal" href="index.html#diagnose"><em>what the diagnose() function says</em></a> about
that document.</p>
</div>
</div>
<div class="section" id="quick-start">
<h1>Quick Start<a class="headerlink" href="index.html#quick-start" title="Permalink to this headline">¶</a></h1>
<p>Here&#8217;s an HTML document I&#8217;ll be using as an example throughout this
document. It&#8217;s part of a story from <cite>Alice in Wonderland</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">html_doc</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span>
<span class="s">&lt;html&gt;&lt;head&gt;&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;&lt;/head&gt;</span>
<span class="s">&lt;body&gt;</span>
<span class="s">&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;Once upon a time there were three little sisters; and their names were</span>
<span class="s">&lt;a href=&quot;http://example.com/elsie&quot; class=&quot;sister&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="s">&lt;a href=&quot;http://example.com/lacie&quot; class=&quot;sister&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt; and</span>
<span class="s">&lt;a href=&quot;http://example.com/tillie&quot; class=&quot;sister&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;;</span>
<span class="s">and they lived at the bottom of a well.&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
<span class="s">&quot;&quot;&quot;</span>
</pre></div>
</div>
<p>Running the &#8220;three sisters&#8221; document through Beautiful Soup gives us a
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object, which represents the document as a nested
data structure:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">BeautifulSoup</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;head&gt;</span>
<span class="c">#   &lt;title&gt;</span>
<span class="c">#    The Dormouse&#39;s story</span>
<span class="c">#   &lt;/title&gt;</span>
<span class="c">#  &lt;/head&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p class=&quot;title&quot;&gt;</span>
<span class="c">#    &lt;b&gt;</span>
<span class="c">#     The Dormouse&#39;s story</span>
<span class="c">#    &lt;/b&gt;</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#   &lt;p class=&quot;story&quot;&gt;</span>
<span class="c">#    Once upon a time there were three little sisters; and their names were</span>
<span class="c">#    &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;</span>
<span class="c">#     Elsie</span>
<span class="c">#    &lt;/a&gt;</span>
<span class="c">#    ,</span>
<span class="c">#    &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;</span>
<span class="c">#     Lacie</span>
<span class="c">#    &lt;/a&gt;</span>
<span class="c">#    and</span>
<span class="c">#    &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link2&quot;&gt;</span>
<span class="c">#     Tillie</span>
<span class="c">#    &lt;/a&gt;</span>
<span class="c">#    ; and they lived at the bottom of a well.</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#   &lt;p class=&quot;story&quot;&gt;</span>
<span class="c">#    ...</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>Here are some simple ways to navigate that data structure:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">title</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">title</span><span class="o">.</span><span class="n">name</span>
<span class="c"># u&#39;title&#39;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">title</span><span class="o">.</span><span class="n">string</span>
<span class="c"># u&#39;The Dormouse&#39;s story&#39;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">title</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">name</span>
<span class="c"># u&#39;head&#39;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">p</span>
<span class="c"># &lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">p</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="c"># u&#39;title&#39;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;link3&quot;</span><span class="p">)</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;</span>
</pre></div>
</div>
<p>One common task is extracting all the URLs found within a page&#8217;s &lt;a&gt; tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">link</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">link</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;href&#39;</span><span class="p">))</span>
<span class="c"># http://example.com/elsie</span>
<span class="c"># http://example.com/lacie</span>
<span class="c"># http://example.com/tillie</span>
</pre></div>
</div>
<p>Another common task is extracting all the text from a page:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">get_text</span><span class="p">())</span>
<span class="c"># The Dormouse&#39;s story</span>
<span class="c">#</span>
<span class="c"># The Dormouse&#39;s story</span>
<span class="c">#</span>
<span class="c"># Once upon a time there were three little sisters; and their names were</span>
<span class="c"># Elsie,</span>
<span class="c"># Lacie and</span>
<span class="c"># Tillie;</span>
<span class="c"># and they lived at the bottom of a well.</span>
<span class="c">#</span>
<span class="c"># ...</span>
</pre></div>
</div>
<p>Does this look like what you need? If so, read on.</p>
</div>
<div class="section" id="installing-beautiful-soup">
<h1>Installing Beautiful Soup<a class="headerlink" href="index.html#installing-beautiful-soup" title="Permalink to this headline">¶</a></h1>
<p>If you&#8217;re using a recent version of Debian or Ubuntu Linux, you can
install Beautiful Soup with the system package manager:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">python-bs4</span></tt></p>
<p>Beautiful Soup 4 is published through PyPi, so if you can&#8217;t install it
with the system packager, you can install it with <tt class="docutils literal"><span class="pre">easy_install</span></tt> or
<tt class="docutils literal"><span class="pre">pip</span></tt>. The package name is <tt class="docutils literal"><span class="pre">beautifulsoup4</span></tt>, and the same package
works on Python 2 and Python 3.</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">easy_install</span> <span class="pre">beautifulsoup4</span></tt></p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">beautifulsoup4</span></tt></p>
<p>(The <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> package is probably <cite>not</cite> what you want. That&#8217;s
the previous major release, <a class="reference external" href="http://www.crummy.com/software/BeautifulSoup/bs3/documentation.html">Beautiful Soup 3</a>. Lots of software uses
BS3, so it&#8217;s still available, but if you&#8217;re writing new code you
should install <tt class="docutils literal"><span class="pre">beautifulsoup4</span></tt>.)</p>
<p>If you don&#8217;t have <tt class="docutils literal"><span class="pre">easy_install</span></tt> or <tt class="docutils literal"><span class="pre">pip</span></tt> installed, you can
<a class="reference external" href="http://www.crummy.com/software/BeautifulSoup/download/4.x/">download the Beautiful Soup 4 source tarball</a> and
install it with <tt class="docutils literal"><span class="pre">setup.py</span></tt>.</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></tt></p>
<p>If all else fails, the license for Beautiful Soup allows you to
package the entire library with your application. You can download the
tarball, copy its <tt class="docutils literal"><span class="pre">bs4</span></tt> directory into your application&#8217;s codebase,
and use Beautiful Soup without installing it at all.</p>
<p>I use Python 2.7 and Python 3.2 to develop Beautiful Soup, but it
should work with other recent versions.</p>
<div class="section" id="problems-after-installation">
<h2>Problems after installation<a class="headerlink" href="index.html#problems-after-installation" title="Permalink to this headline">¶</a></h2>
<p>Beautiful Soup is packaged as Python 2 code. When you install it for
use with Python 3, it&#8217;s automatically converted to Python 3 code. If
you don&#8217;t install the package, the code won&#8217;t be converted. There have
also been reports on Windows machines of the wrong version being
installed.</p>
<p>If you get the <tt class="docutils literal"><span class="pre">ImportError</span></tt> &#8220;No module named HTMLParser&#8221;, your
problem is that you&#8217;re running the Python 2 version of the code under
Python 3.</p>
<p>If you get the <tt class="docutils literal"><span class="pre">ImportError</span></tt> &#8220;No module named html.parser&#8221;, your
problem is that you&#8217;re running the Python 3 version of the code under
Python 2.</p>
<p>In both cases, your best bet is to completely remove the Beautiful
Soup installation from your system (including any directory created
when you unzipped the tarball) and try the installation again.</p>
<p>If you get the <tt class="docutils literal"><span class="pre">SyntaxError</span></tt> &#8220;Invalid syntax&#8221; on the line
<tt class="docutils literal"><span class="pre">ROOT_TAG_NAME</span> <span class="pre">=</span> <span class="pre">u'[document]'</span></tt>, you need to convert the Python 2
code to Python 3. You can do this either by installing the package:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">python3</span> <span class="pre">setup.py</span> <span class="pre">install</span></tt></p>
<p>or by manually running Python&#8217;s <tt class="docutils literal"><span class="pre">2to3</span></tt> conversion script on the
<tt class="docutils literal"><span class="pre">bs4</span></tt> directory:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">2to3-3.2</span> <span class="pre">-w</span> <span class="pre">bs4</span></tt></p>
</div>
<div class="section" id="installing-a-parser">
<span id="parser-installation"></span><h2>Installing a parser<a class="headerlink" href="index.html#installing-a-parser" title="Permalink to this headline">¶</a></h2>
<p>Beautiful Soup supports the HTML parser included in Python&#8217;s standard
library, but it also supports a number of third-party Python parsers.
One is the <a class="reference external" href="http://lxml.de/">lxml parser</a>. Depending on your setup,
you might install lxml with one of these commands:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">python-lxml</span></tt></p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">easy_install</span> <span class="pre">lxml</span></tt></p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">lxml</span></tt></p>
<p>Another alternative is the pure-Python <a class="reference external" href="http://code.google.com/p/html5lib/">html5lib parser</a>, which parses HTML the way a
web browser does. Depending on your setup, you might install html5lib
with one of these commands:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">python-html5lib</span></tt></p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">easy_install</span> <span class="pre">html5lib</span></tt></p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">html5lib</span></tt></p>
<p>This table summarizes the advantages and disadvantages of each parser library:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="35%" />
<col width="26%" />
<col width="21%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Parser</td>
<td>Typical usage</td>
<td>Advantages</td>
<td>Disadvantages</td>
</tr>
<tr class="row-even"><td>Python&#8217;s html.parser</td>
<td><tt class="docutils literal"><span class="pre">BeautifulSoup(markup,</span> <span class="pre">&quot;html.parser&quot;)</span></tt></td>
<td><ul class="first last simple">
<li>Batteries included</li>
<li>Decent speed</li>
<li>Lenient (as of Python 2.7.3
and 3.2.)</li>
</ul>
</td>
<td><ul class="first last simple">
<li>Not very lenient
(before Python 2.7.3
or 3.2.2)</li>
</ul>
</td>
</tr>
<tr class="row-odd"><td>lxml&#8217;s HTML parser</td>
<td><tt class="docutils literal"><span class="pre">BeautifulSoup(markup,</span> <span class="pre">&quot;lxml&quot;)</span></tt></td>
<td><ul class="first last simple">
<li>Very fast</li>
<li>Lenient</li>
</ul>
</td>
<td><ul class="first last simple">
<li>External C dependency</li>
</ul>
</td>
</tr>
<tr class="row-even"><td>lxml&#8217;s XML parser</td>
<td><tt class="docutils literal"><span class="pre">BeautifulSoup(markup,</span> <span class="pre">[&quot;lxml&quot;,</span> <span class="pre">&quot;xml&quot;])</span></tt>
<tt class="docutils literal"><span class="pre">BeautifulSoup(markup,</span> <span class="pre">&quot;xml&quot;)</span></tt></td>
<td><ul class="first last simple">
<li>Very fast</li>
<li>The only currently supported
XML parser</li>
</ul>
</td>
<td><ul class="first last simple">
<li>External C dependency</li>
</ul>
</td>
</tr>
<tr class="row-odd"><td>html5lib</td>
<td><tt class="docutils literal"><span class="pre">BeautifulSoup(markup,</span> <span class="pre">&quot;html5lib&quot;)</span></tt></td>
<td><ul class="first last simple">
<li>Extremely lenient</li>
<li>Parses pages the same way a
web browser does</li>
<li>Creates valid HTML5</li>
</ul>
</td>
<td><ul class="first last simple">
<li>Very slow</li>
<li>External Python
dependency</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If you can, I recommend you install and use lxml for speed. If you&#8217;re
using a version of Python 2 earlier than 2.7.3, or a version of Python
3 earlier than 3.2.2, it&#8217;s <cite>essential</cite> that you install lxml or
html5lib&#8211;Python&#8217;s built-in HTML parser is just not very good in older
versions.</p>
<p>Note that if a document is invalid, different parsers will generate
different Beautiful Soup trees for it. See <a class="reference internal" href="index.html#differences-between-parsers">Differences
between parsers</a> for details.</p>
</div>
</div>
<div class="section" id="making-the-soup">
<h1>Making the soup<a class="headerlink" href="index.html#making-the-soup" title="Permalink to this headline">¶</a></h1>
<p>To parse a document, pass it into the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt>
constructor. You can pass in a string or an open filehandle:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">BeautifulSoup</span>

<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="s">&quot;index.html&quot;</span><span class="p">))</span>

<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;html&gt;data&lt;/html&gt;&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>First, the document is converted to Unicode, and HTML entities are
converted to Unicode characters:</p>
<div class="highlight-python"><pre>BeautifulSoup("Sacr&amp;eacute; bleu!")
&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;Sacré bleu!&lt;/body&gt;&lt;/html&gt;</pre>
</div>
<p>Beautiful Soup then parses the document using the best available
parser. It will use an HTML parser unless you specifically tell it to
use an XML parser. (See <a class="reference internal" href="index.html#id17">Parsing XML</a>.)</p>
</div>
<div class="section" id="kinds-of-objects">
<h1>Kinds of objects<a class="headerlink" href="index.html#kinds-of-objects" title="Permalink to this headline">¶</a></h1>
<p>Beautiful Soup transforms a complex HTML document into a complex tree
of Python objects. But you&#8217;ll only ever have to deal with about four
<cite>kinds</cite> of objects: <tt class="docutils literal"><span class="pre">Tag</span></tt>, <tt class="docutils literal"><span class="pre">NavigableString</span></tt>, <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt>,
and <tt class="docutils literal"><span class="pre">Comment</span></tt>.</p>
<div class="section" id="tag">
<span id="id4"></span><h2><tt class="docutils literal"><span class="pre">Tag</span></tt><a class="headerlink" href="index.html#tag" title="Permalink to this headline">¶</a></h2>
<p>A <tt class="docutils literal"><span class="pre">Tag</span></tt> object corresponds to an XML or HTML tag in the original document:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;b class=&quot;boldest&quot;&gt;Extremely bold&lt;/b&gt;&#39;</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">b</span>
<span class="nb">type</span><span class="p">(</span><span class="n">tag</span><span class="p">)</span>
<span class="c"># &lt;class &#39;bs4.element.Tag&#39;&gt;</span>
</pre></div>
</div>
<p>Tags have a lot of attributes and methods, and I&#8217;ll cover most of them
in <a class="reference internal" href="index.html#navigating-the-tree">Navigating the tree</a> and <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>. For now, the most
important features of a tag are its name and attributes.</p>
<div class="section" id="name">
<h3>Name<a class="headerlink" href="index.html#name" title="Permalink to this headline">¶</a></h3>
<p>Every tag has a name, accessible as <tt class="docutils literal"><span class="pre">.name</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="o">.</span><span class="n">name</span>
<span class="c"># u&#39;b&#39;</span>
</pre></div>
</div>
<p>If you change a tag&#8217;s name, the change will be reflected in any HTML
markup generated by Beautiful Soup:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">&quot;blockquote&quot;</span>
<span class="n">tag</span>
<span class="c"># &lt;blockquote class=&quot;boldest&quot;&gt;Extremely bold&lt;/blockquote&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="attributes">
<h3>Attributes<a class="headerlink" href="index.html#attributes" title="Permalink to this headline">¶</a></h3>
<p>A tag may have any number of attributes. The tag <tt class="docutils literal"><span class="pre">&lt;b</span>
<span class="pre">class=&quot;boldest&quot;&gt;</span></tt> has an attribute &#8220;class&#8221; whose value is
&#8220;boldest&#8221;. You can access a tag&#8217;s attributes by treating the tag like
a dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="c"># u&#39;boldest&#39;</span>
</pre></div>
</div>
<p>You can access that dictionary directly as <tt class="docutils literal"><span class="pre">.attrs</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="o">.</span><span class="n">attrs</span>
<span class="c"># {u&#39;class&#39;: u&#39;boldest&#39;}</span>
</pre></div>
</div>
<p>You can add, remove, and modify a tag&#8217;s attributes. Again, this is
done by treating the tag as a dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s">&#39;verybold&#39;</span>
<span class="n">tag</span><span class="p">[</span><span class="s">&#39;id&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">tag</span>
<span class="c"># &lt;blockquote class=&quot;verybold&quot; id=&quot;1&quot;&gt;Extremely bold&lt;/blockquote&gt;</span>

<span class="k">del</span> <span class="n">tag</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="k">del</span> <span class="n">tag</span><span class="p">[</span><span class="s">&#39;id&#39;</span><span class="p">]</span>
<span class="n">tag</span>
<span class="c"># &lt;blockquote&gt;Extremely bold&lt;/blockquote&gt;</span>

<span class="n">tag</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="c"># KeyError: &#39;class&#39;</span>
<span class="k">print</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&#39;class&#39;</span><span class="p">))</span>
<span class="c"># None</span>
</pre></div>
</div>
<div class="section" id="multi-valued-attributes">
<span id="multivalue"></span><h4>Multi-valued attributes<a class="headerlink" href="index.html#multi-valued-attributes" title="Permalink to this headline">¶</a></h4>
<p>HTML 4 defines a few attributes that can have multiple values. HTML 5
removes a couple of them, but defines a few more. The most common
multi-valued attribute is <tt class="docutils literal"><span class="pre">class</span></tt> (that is, a tag can have more than
one CSS class). Others include <tt class="docutils literal"><span class="pre">rel</span></tt>, <tt class="docutils literal"><span class="pre">rev</span></tt>, <tt class="docutils literal"><span class="pre">accept-charset</span></tt>,
<tt class="docutils literal"><span class="pre">headers</span></tt>, and <tt class="docutils literal"><span class="pre">accesskey</span></tt>. Beautiful Soup presents the value(s)
of a multi-valued attribute as a list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">css_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;&#39;</span><span class="p">)</span>
<span class="n">css_soup</span><span class="o">.</span><span class="n">p</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="c"># [&quot;body&quot;, &quot;strikeout&quot;]</span>

<span class="n">css_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;p class=&quot;body&quot;&gt;&lt;/p&gt;&#39;</span><span class="p">)</span>
<span class="n">css_soup</span><span class="o">.</span><span class="n">p</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="c"># [&quot;body&quot;]</span>
</pre></div>
</div>
<p>If an attribute <cite>looks</cite> like it has more than one value, but it&#8217;s not
a multi-valued attribute as defined by any version of the HTML
standard, Beautiful Soup will leave the attribute alone:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">id_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;p id=&quot;my id&quot;&gt;&lt;/p&gt;&#39;</span><span class="p">)</span>
<span class="n">id_soup</span><span class="o">.</span><span class="n">p</span><span class="p">[</span><span class="s">&#39;id&#39;</span><span class="p">]</span>
<span class="c"># &#39;my id&#39;</span>
</pre></div>
</div>
<p>When you turn a tag back into a string, multiple attribute values are
consolidated:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">rel_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;p&gt;Back to the &lt;a rel=&quot;index&quot;&gt;homepage&lt;/a&gt;&lt;/p&gt;&#39;</span><span class="p">)</span>
<span class="n">rel_soup</span><span class="o">.</span><span class="n">a</span><span class="p">[</span><span class="s">&#39;rel&#39;</span><span class="p">]</span>
<span class="c"># [&#39;index&#39;]</span>
<span class="n">rel_soup</span><span class="o">.</span><span class="n">a</span><span class="p">[</span><span class="s">&#39;rel&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;index&#39;</span><span class="p">,</span> <span class="s">&#39;contents&#39;</span><span class="p">]</span>
<span class="k">print</span><span class="p">(</span><span class="n">rel_soup</span><span class="o">.</span><span class="n">p</span><span class="p">)</span>
<span class="c"># &lt;p&gt;Back to the &lt;a rel=&quot;index contents&quot;&gt;homepage&lt;/a&gt;&lt;/p&gt;</span>
</pre></div>
</div>
<p>If you parse a document as XML, there are no multi-valued attributes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">xml_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;&#39;</span><span class="p">,</span> <span class="s">&#39;xml&#39;</span><span class="p">)</span>
<span class="n">xml_soup</span><span class="o">.</span><span class="n">p</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="c"># u&#39;body strikeout&#39;</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="navigablestring">
<h2><tt class="docutils literal"><span class="pre">NavigableString</span></tt><a class="headerlink" href="index.html#navigablestring" title="Permalink to this headline">¶</a></h2>
<p>A string corresponds to a bit of text within a tag. Beautiful Soup
uses the <tt class="docutils literal"><span class="pre">NavigableString</span></tt> class to contain these bits of text:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="o">.</span><span class="n">string</span>
<span class="c"># u&#39;Extremely bold&#39;</span>
<span class="nb">type</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">string</span><span class="p">)</span>
<span class="c"># &lt;class &#39;bs4.element.NavigableString&#39;&gt;</span>
</pre></div>
</div>
<p>A <tt class="docutils literal"><span class="pre">NavigableString</span></tt> is just like a Python Unicode string, except
that it also supports some of the features described in <a class="reference internal" href="index.html#navigating-the-tree">Navigating
the tree</a> and <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>. You can convert a
<tt class="docutils literal"><span class="pre">NavigableString</span></tt> to a Unicode string with <tt class="docutils literal"><span class="pre">unicode()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">unicode_string</span> <span class="o">=</span> <span class="nb">unicode</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">string</span><span class="p">)</span>
<span class="n">unicode_string</span>
<span class="c"># u&#39;Extremely bold&#39;</span>
<span class="nb">type</span><span class="p">(</span><span class="n">unicode_string</span><span class="p">)</span>
<span class="c"># &lt;type &#39;unicode&#39;&gt;</span>
</pre></div>
</div>
<p>You can&#8217;t edit a string in place, but you can replace one string with
another, using <a class="reference internal" href="index.html#replace-with"><em>replace_with()</em></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tag</span><span class="o">.</span><span class="n">string</span><span class="o">.</span><span class="n">replace_with</span><span class="p">(</span><span class="s">&quot;No longer bold&quot;</span><span class="p">)</span>
<span class="n">tag</span>
<span class="c"># &lt;blockquote&gt;No longer bold&lt;/blockquote&gt;</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">NavigableString</span></tt> supports most of the features described in
<a class="reference internal" href="index.html#navigating-the-tree">Navigating the tree</a> and <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>, but not all of
them. In particular, since a string can&#8217;t contain anything (the way a
tag may contain a string or another tag), strings don&#8217;t support the
<tt class="docutils literal"><span class="pre">.contents</span></tt> or <tt class="docutils literal"><span class="pre">.string</span></tt> attributes, or the <tt class="docutils literal"><span class="pre">find()</span></tt> method.</p>
<p>If you want to use a <tt class="docutils literal"><span class="pre">NavigableString</span></tt> outside of Beautiful Soup,
you should call <tt class="docutils literal"><span class="pre">unicode()</span></tt> on it to turn it into a normal Python
Unicode string. If you don&#8217;t, your string will carry around a
reference to the entire Beautiful Soup parse tree, even when you&#8217;re
done using Beautiful Soup. This is a big waste of memory.</p>
</div>
<div class="section" id="beautifulsoup">
<h2><tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt><a class="headerlink" href="index.html#beautifulsoup" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object itself represents the document as a
whole. For most purposes, you can treat it as a <a class="reference internal" href="index.html#tag"><em>Tag</em></a>
object. This means it supports most of the methods described in
<a class="reference internal" href="index.html#navigating-the-tree">Navigating the tree</a> and <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>.</p>
<p>Since the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object doesn&#8217;t correspond to an actual
HTML or XML tag, it has no name and no attributes. But sometimes it&#8217;s
useful to look at its <tt class="docutils literal"><span class="pre">.name</span></tt>, so it&#8217;s been given the special
<tt class="docutils literal"><span class="pre">.name</span></tt> &#8220;[document]&#8221;:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">name</span>
<span class="c"># u&#39;[document]&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="comments-and-other-special-strings">
<h2>Comments and other special strings<a class="headerlink" href="index.html#comments-and-other-special-strings" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">Tag</span></tt>, <tt class="docutils literal"><span class="pre">NavigableString</span></tt>, and <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> cover almost
everything you&#8217;ll see in an HTML or XML file, but there are a few
leftover bits. The only one you&#8217;ll probably ever need to worry about
is the comment:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&quot;&lt;b&gt;&lt;!--Hey, buddy. Want to buy a used parser?--&gt;&lt;/b&gt;&quot;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">comment</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">string</span>
<span class="nb">type</span><span class="p">(</span><span class="n">comment</span><span class="p">)</span>
<span class="c"># &lt;class &#39;bs4.element.Comment&#39;&gt;</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">Comment</span></tt> object is just a special type of <tt class="docutils literal"><span class="pre">NavigableString</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">comment</span>
<span class="c"># u&#39;Hey, buddy. Want to buy a used parser&#39;</span>
</pre></div>
</div>
<p>But when it appears as part of an HTML document, a <tt class="docutils literal"><span class="pre">Comment</span></tt> is
displayed with special formatting:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;b&gt;</span>
<span class="c">#  &lt;!--Hey, buddy. Want to buy a used parser?--&gt;</span>
<span class="c"># &lt;/b&gt;</span>
</pre></div>
</div>
<p>Beautiful Soup defines classes for anything else that might show up in
an XML document: <tt class="docutils literal"><span class="pre">CData</span></tt>, <tt class="docutils literal"><span class="pre">ProcessingInstruction</span></tt>,
<tt class="docutils literal"><span class="pre">Declaration</span></tt>, and <tt class="docutils literal"><span class="pre">Doctype</span></tt>. Just like <tt class="docutils literal"><span class="pre">Comment</span></tt>, these classes
are subclasses of <tt class="docutils literal"><span class="pre">NavigableString</span></tt> that add something extra to the
string. Here&#8217;s an example that replaces the comment with a CDATA
block:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">CData</span>
<span class="n">cdata</span> <span class="o">=</span> <span class="n">CData</span><span class="p">(</span><span class="s">&quot;A CDATA block&quot;</span><span class="p">)</span>
<span class="n">comment</span><span class="o">.</span><span class="n">replace_with</span><span class="p">(</span><span class="n">cdata</span><span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;b&gt;</span>
<span class="c">#  &lt;![CDATA[A CDATA block]]&gt;</span>
<span class="c"># &lt;/b&gt;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="navigating-the-tree">
<h1>Navigating the tree<a class="headerlink" href="index.html#navigating-the-tree" title="Permalink to this headline">¶</a></h1>
<p>Here&#8217;s the &#8220;Three sisters&#8221; HTML document again:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">html_doc</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span>
<span class="s">&lt;html&gt;&lt;head&gt;&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;&lt;/head&gt;</span>

<span class="s">&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;Once upon a time there were three little sisters; and their names were</span>
<span class="s">&lt;a href=&quot;http://example.com/elsie&quot; class=&quot;sister&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="s">&lt;a href=&quot;http://example.com/lacie&quot; class=&quot;sister&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt; and</span>
<span class="s">&lt;a href=&quot;http://example.com/tillie&quot; class=&quot;sister&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;;</span>
<span class="s">and they lived at the bottom of a well.&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
<span class="s">&quot;&quot;&quot;</span>

<span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">BeautifulSoup</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">)</span>
</pre></div>
</div>
<p>I&#8217;ll use this as an example to show you how to move from one part of
a document to another.</p>
<div class="section" id="going-down">
<h2>Going down<a class="headerlink" href="index.html#going-down" title="Permalink to this headline">¶</a></h2>
<p>Tags may contain strings and other tags. These elements are the tag&#8217;s
<cite>children</cite>. Beautiful Soup provides a lot of different attributes for
navigating and iterating over a tag&#8217;s children.</p>
<p>Note that Beautiful Soup strings don&#8217;t support any of these
attributes, because a string can&#8217;t have children.</p>
<div class="section" id="navigating-using-tag-names">
<h3>Navigating using tag names<a class="headerlink" href="index.html#navigating-using-tag-names" title="Permalink to this headline">¶</a></h3>
<p>The simplest way to navigate the parse tree is to say the name of the
tag you want. If you want the &lt;head&gt; tag, just say <tt class="docutils literal"><span class="pre">soup.head</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">head</span>
<span class="c"># &lt;head&gt;&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;&lt;/head&gt;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">title</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
</pre></div>
</div>
<p>You can do use this trick again and again to zoom in on a certain part
of the parse tree. This code gets the first &lt;b&gt; tag beneath the &lt;body&gt; tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">body</span><span class="o">.</span><span class="n">b</span>
<span class="c"># &lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;</span>
</pre></div>
</div>
<p>Using a tag name as an attribute will give you only the <cite>first</cite> tag by that
name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>
</pre></div>
</div>
<p>If you need to get <cite>all</cite> the &lt;a&gt; tags, or anything more complicated
than the first tag with a certain name, you&#8217;ll need to use one of the
methods described in <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>, such as <cite>find_all()</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="contents-and-children">
<h3><tt class="docutils literal"><span class="pre">.contents</span></tt> and <tt class="docutils literal"><span class="pre">.children</span></tt><a class="headerlink" href="index.html#contents-and-children" title="Permalink to this headline">¶</a></h3>
<p>A tag&#8217;s children are available in a list called <tt class="docutils literal"><span class="pre">.contents</span></tt>:</p>
<div class="highlight-python"><pre>head_tag = soup.head
head_tag
# &lt;head&gt;&lt;title&gt;The Dormouse's story&lt;/title&gt;&lt;/head&gt;

head_tag.contents
[&lt;title&gt;The Dormouse's story&lt;/title&gt;]

title_tag = head_tag.contents[0]
title_tag
# &lt;title&gt;The Dormouse's story&lt;/title&gt;
title_tag.contents
# [u'The Dormouse's story']</pre>
</div>
<p>The <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object itself has children. In this case, the
&lt;html&gt; tag is the child of the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">len</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">contents</span><span class="p">)</span>
<span class="c"># 1</span>
<span class="n">soup</span><span class="o">.</span><span class="n">contents</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">name</span>
<span class="c"># u&#39;html&#39;</span>
</pre></div>
</div>
<p>A string does not have <tt class="docutils literal"><span class="pre">.contents</span></tt>, because it can&#8217;t contain
anything:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">text</span> <span class="o">=</span> <span class="n">title_tag</span><span class="o">.</span><span class="n">contents</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">text</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># AttributeError: &#39;NavigableString&#39; object has no attribute &#39;contents&#39;</span>
</pre></div>
</div>
<p>Instead of getting them as a list, you can iterate over a tag&#8217;s
children using the <tt class="docutils literal"><span class="pre">.children</span></tt> generator:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">title_tag</span><span class="o">.</span><span class="n">children</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="n">child</span><span class="p">)</span>
<span class="c"># The Dormouse&#39;s story</span>
</pre></div>
</div>
</div>
<div class="section" id="descendants">
<h3><tt class="docutils literal"><span class="pre">.descendants</span></tt><a class="headerlink" href="index.html#descendants" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">.contents</span></tt> and <tt class="docutils literal"><span class="pre">.children</span></tt> attributes only consider a tag&#8217;s
<cite>direct</cite> children. For instance, the &lt;head&gt; tag has a single direct
child&#8211;the &lt;title&gt; tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">head_tag</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>
</pre></div>
</div>
<p>But the &lt;title&gt; tag itself has a child: the string &#8220;The Dormouse&#8217;s
story&#8221;. There&#8217;s a sense in which that string is also a child of the
&lt;head&gt; tag. The <tt class="docutils literal"><span class="pre">.descendants</span></tt> attribute lets you iterate over <cite>all</cite>
of a tag&#8217;s children, recursively: its direct children, the children of
its direct children, and so on:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">head_tag</span><span class="o">.</span><span class="n">descendants</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="n">child</span><span class="p">)</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
<span class="c"># The Dormouse&#39;s story</span>
</pre></div>
</div>
<p>The &lt;head&gt; tag has only one child, but it has two descendants: the
&lt;title&gt; tag and the &lt;title&gt; tag&#8217;s child. The <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object
only has one direct child (the &lt;html&gt; tag), but it has a whole lot of
descendants:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">children</span><span class="p">))</span>
<span class="c"># 1</span>
<span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">descendants</span><span class="p">))</span>
<span class="c"># 25</span>
</pre></div>
</div>
</div>
<div class="section" id="string">
<span id="id5"></span><h3><tt class="docutils literal"><span class="pre">.string</span></tt><a class="headerlink" href="index.html#string" title="Permalink to this headline">¶</a></h3>
<p>If a tag has only one child, and that child is a <tt class="docutils literal"><span class="pre">NavigableString</span></tt>,
the child is made available as <tt class="docutils literal"><span class="pre">.string</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">title_tag</span><span class="o">.</span><span class="n">string</span>
<span class="c"># u&#39;The Dormouse&#39;s story&#39;</span>
</pre></div>
</div>
<p>If a tag&#8217;s only child is another tag, and <cite>that</cite> tag has a
<tt class="docutils literal"><span class="pre">.string</span></tt>, then the parent tag is considered to have the same
<tt class="docutils literal"><span class="pre">.string</span></tt> as its child:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">head_tag</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>

<span class="n">head_tag</span><span class="o">.</span><span class="n">string</span>
<span class="c"># u&#39;The Dormouse&#39;s story&#39;</span>
</pre></div>
</div>
<p>If a tag contains more than one thing, then it&#8217;s not clear what
<tt class="docutils literal"><span class="pre">.string</span></tt> should refer to, so <tt class="docutils literal"><span class="pre">.string</span></tt> is defined to be
<tt class="docutils literal"><span class="pre">None</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">html</span><span class="o">.</span><span class="n">string</span><span class="p">)</span>
<span class="c"># None</span>
</pre></div>
</div>
</div>
<div class="section" id="strings-and-stripped-strings">
<span id="string-generators"></span><h3><tt class="docutils literal"><span class="pre">.strings</span></tt> and <tt class="docutils literal"><span class="pre">stripped_strings</span></tt><a class="headerlink" href="index.html#strings-and-stripped-strings" title="Permalink to this headline">¶</a></h3>
<p>If there&#8217;s more than one thing inside a tag, you can still look at
just the strings. Use the <tt class="docutils literal"><span class="pre">.strings</span></tt> generator:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">string</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">strings</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">string</span><span class="p">))</span>
<span class="c"># u&quot;The Dormouse&#39;s story&quot;</span>
<span class="c"># u&#39;\n\n&#39;</span>
<span class="c"># u&quot;The Dormouse&#39;s story&quot;</span>
<span class="c"># u&#39;\n\n&#39;</span>
<span class="c"># u&#39;Once upon a time there were three little sisters; and their names were\n&#39;</span>
<span class="c"># u&#39;Elsie&#39;</span>
<span class="c"># u&#39;,\n&#39;</span>
<span class="c"># u&#39;Lacie&#39;</span>
<span class="c"># u&#39; and\n&#39;</span>
<span class="c"># u&#39;Tillie&#39;</span>
<span class="c"># u&#39;;\nand they lived at the bottom of a well.&#39;</span>
<span class="c"># u&#39;\n\n&#39;</span>
<span class="c"># u&#39;...&#39;</span>
<span class="c"># u&#39;\n&#39;</span>
</pre></div>
</div>
<p>These strings tend to have a lot of extra whitespace, which you can
remove by using the <tt class="docutils literal"><span class="pre">.stripped_strings</span></tt> generator instead:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">string</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">stripped_strings</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">string</span><span class="p">))</span>
<span class="c"># u&quot;The Dormouse&#39;s story&quot;</span>
<span class="c"># u&quot;The Dormouse&#39;s story&quot;</span>
<span class="c"># u&#39;Once upon a time there were three little sisters; and their names were&#39;</span>
<span class="c"># u&#39;Elsie&#39;</span>
<span class="c"># u&#39;,&#39;</span>
<span class="c"># u&#39;Lacie&#39;</span>
<span class="c"># u&#39;and&#39;</span>
<span class="c"># u&#39;Tillie&#39;</span>
<span class="c"># u&#39;;\nand they lived at the bottom of a well.&#39;</span>
<span class="c"># u&#39;...&#39;</span>
</pre></div>
</div>
<p>Here, strings consisting entirely of whitespace are ignored, and
whitespace at the beginning and end of strings is removed.</p>
</div>
</div>
<div class="section" id="going-up">
<h2>Going up<a class="headerlink" href="index.html#going-up" title="Permalink to this headline">¶</a></h2>
<p>Continuing the &#8220;family tree&#8221; analogy, every tag and every string has a
<cite>parent</cite>: the tag that contains it.</p>
<div class="section" id="parent">
<span id="id6"></span><h3><tt class="docutils literal"><span class="pre">.parent</span></tt><a class="headerlink" href="index.html#parent" title="Permalink to this headline">¶</a></h3>
<p>You can access an element&#8217;s parent with the <tt class="docutils literal"><span class="pre">.parent</span></tt> attribute. In
the example &#8220;three sisters&#8221; document, the &lt;head&gt; tag is the parent
of the &lt;title&gt; tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">title_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">title</span>
<span class="n">title_tag</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
<span class="n">title_tag</span><span class="o">.</span><span class="n">parent</span>
<span class="c"># &lt;head&gt;&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;&lt;/head&gt;</span>
</pre></div>
</div>
<p>The title string itself has a parent: the &lt;title&gt; tag that contains
it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">title_tag</span><span class="o">.</span><span class="n">string</span><span class="o">.</span><span class="n">parent</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
</pre></div>
</div>
<p>The parent of a top-level tag like &lt;html&gt; is the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object
itself:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">html_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">html</span>
<span class="nb">type</span><span class="p">(</span><span class="n">html_tag</span><span class="o">.</span><span class="n">parent</span><span class="p">)</span>
<span class="c"># &lt;class &#39;bs4.BeautifulSoup&#39;&gt;</span>
</pre></div>
</div>
<p>And the <tt class="docutils literal"><span class="pre">.parent</span></tt> of a <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object is defined as None:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">parent</span><span class="p">)</span>
<span class="c"># None</span>
</pre></div>
</div>
</div>
<div class="section" id="parents">
<span id="id7"></span><h3><tt class="docutils literal"><span class="pre">.parents</span></tt><a class="headerlink" href="index.html#parents" title="Permalink to this headline">¶</a></h3>
<p>You can iterate over all of an element&#8217;s parents with
<tt class="docutils literal"><span class="pre">.parents</span></tt>. This example uses <tt class="docutils literal"><span class="pre">.parents</span></tt> to travel from an &lt;a&gt; tag
buried deep within the document, to the very top of the document:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">link</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="n">link</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>
<span class="k">for</span> <span class="n">parent</span> <span class="ow">in</span> <span class="n">link</span><span class="o">.</span><span class="n">parents</span><span class="p">:</span>
    <span class="k">if</span> <span class="n">parent</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
        <span class="k">print</span><span class="p">(</span><span class="n">parent</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">print</span><span class="p">(</span><span class="n">parent</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="c"># p</span>
<span class="c"># body</span>
<span class="c"># html</span>
<span class="c"># [document]</span>
<span class="c"># None</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="going-sideways">
<h2>Going sideways<a class="headerlink" href="index.html#going-sideways" title="Permalink to this headline">¶</a></h2>
<p>Consider a simple document like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sibling_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;b&gt;text1&lt;/b&gt;&lt;c&gt;text2&lt;/c&gt;&lt;/b&gt;&lt;/a&gt;&quot;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">sibling_soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;a&gt;</span>
<span class="c">#    &lt;b&gt;</span>
<span class="c">#     text1</span>
<span class="c">#    &lt;/b&gt;</span>
<span class="c">#    &lt;c&gt;</span>
<span class="c">#     text2</span>
<span class="c">#    &lt;/c&gt;</span>
<span class="c">#   &lt;/a&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>The &lt;b&gt; tag and the &lt;c&gt; tag are at the same level: they&#8217;re both direct
children of the same tag. We call them <cite>siblings</cite>. When a document is
pretty-printed, siblings show up at the same indentation level. You
can also use this relationship in the code you write.</p>
<div class="section" id="next-sibling-and-previous-sibling">
<h3><tt class="docutils literal"><span class="pre">.next_sibling</span></tt> and <tt class="docutils literal"><span class="pre">.previous_sibling</span></tt><a class="headerlink" href="index.html#next-sibling-and-previous-sibling" title="Permalink to this headline">¶</a></h3>
<p>You can use <tt class="docutils literal"><span class="pre">.next_sibling</span></tt> and <tt class="docutils literal"><span class="pre">.previous_sibling</span></tt> to navigate
between page elements that are on the same level of the parse tree:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sibling_soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">next_sibling</span>
<span class="c"># &lt;c&gt;text2&lt;/c&gt;</span>

<span class="n">sibling_soup</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">previous_sibling</span>
<span class="c"># &lt;b&gt;text1&lt;/b&gt;</span>
</pre></div>
</div>
<p>The &lt;b&gt; tag has a <tt class="docutils literal"><span class="pre">.next_sibling</span></tt>, but no <tt class="docutils literal"><span class="pre">.previous_sibling</span></tt>,
because there&#8217;s nothing before the &lt;b&gt; tag <cite>on the same level of the
tree</cite>. For the same reason, the &lt;c&gt; tag has a <tt class="docutils literal"><span class="pre">.previous_sibling</span></tt>
but no <tt class="docutils literal"><span class="pre">.next_sibling</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">sibling_soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">previous_sibling</span><span class="p">)</span>
<span class="c"># None</span>
<span class="k">print</span><span class="p">(</span><span class="n">sibling_soup</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">next_sibling</span><span class="p">)</span>
<span class="c"># None</span>
</pre></div>
</div>
<p>The strings &#8220;text1&#8221; and &#8220;text2&#8221; are <cite>not</cite> siblings, because they don&#8217;t
have the same parent:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sibling_soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">string</span>
<span class="c"># u&#39;text1&#39;</span>

<span class="k">print</span><span class="p">(</span><span class="n">sibling_soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">string</span><span class="o">.</span><span class="n">next_sibling</span><span class="p">)</span>
<span class="c"># None</span>
</pre></div>
</div>
<p>In real documents, the <tt class="docutils literal"><span class="pre">.next_sibling</span></tt> or <tt class="docutils literal"><span class="pre">.previous_sibling</span></tt> of a
tag will usually be a string containing whitespace. Going back to the
&#8220;three sisters&#8221; document:</p>
<div class="highlight-python"><pre>&lt;a href="http://example.com/elsie" class="sister" id="link1"&gt;Elsie&lt;/a&gt;
&lt;a href="http://example.com/lacie" class="sister" id="link2"&gt;Lacie&lt;/a&gt;
&lt;a href="http://example.com/tillie" class="sister" id="link3"&gt;Tillie&lt;/a&gt;</pre>
</div>
<p>You might think that the <tt class="docutils literal"><span class="pre">.next_sibling</span></tt> of the first &lt;a&gt; tag would
be the second &lt;a&gt; tag. But actually, it&#8217;s a string: the comma and
newline that separate the first &lt;a&gt; tag from the second:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">link</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="n">link</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>

<span class="n">link</span><span class="o">.</span><span class="n">next_sibling</span>
<span class="c"># u&#39;,\n&#39;</span>
</pre></div>
</div>
<p>The second &lt;a&gt; tag is actually the <tt class="docutils literal"><span class="pre">.next_sibling</span></tt> of the comma:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">link</span><span class="o">.</span><span class="n">next_sibling</span><span class="o">.</span><span class="n">next_sibling</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="next-siblings-and-previous-siblings">
<span id="sibling-generators"></span><h3><tt class="docutils literal"><span class="pre">.next_siblings</span></tt> and <tt class="docutils literal"><span class="pre">.previous_siblings</span></tt><a class="headerlink" href="index.html#next-siblings-and-previous-siblings" title="Permalink to this headline">¶</a></h3>
<p>You can iterate over a tag&#8217;s siblings with <tt class="docutils literal"><span class="pre">.next_siblings</span></tt> or
<tt class="docutils literal"><span class="pre">.previous_siblings</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">sibling</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">next_siblings</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">sibling</span><span class="p">))</span>
<span class="c"># u&#39;,\n&#39;</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;</span>
<span class="c"># u&#39; and\n&#39;</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;</span>
<span class="c"># u&#39;; and they lived at the bottom of a well.&#39;</span>
<span class="c"># None</span>

<span class="k">for</span> <span class="n">sibling</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;link3&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">previous_siblings</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">sibling</span><span class="p">))</span>
<span class="c"># &#39; and\n&#39;</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;</span>
<span class="c"># u&#39;,\n&#39;</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>
<span class="c"># u&#39;Once upon a time there were three little sisters; and their names were\n&#39;</span>
<span class="c"># None</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="going-back-and-forth">
<h2>Going back and forth<a class="headerlink" href="index.html#going-back-and-forth" title="Permalink to this headline">¶</a></h2>
<p>Take a look at the beginning of the &#8220;three sisters&#8221; document:</p>
<div class="highlight-python"><pre>&lt;html&gt;&lt;head&gt;&lt;title&gt;The Dormouse's story&lt;/title&gt;&lt;/head&gt;
&lt;p class="title"&gt;&lt;b&gt;The Dormouse's story&lt;/b&gt;&lt;/p&gt;</pre>
</div>
<p>An HTML parser takes this string of characters and turns it into a
series of events: &#8220;open an &lt;html&gt; tag&#8221;, &#8220;open a &lt;head&gt; tag&#8221;, &#8220;open a
&lt;title&gt; tag&#8221;, &#8220;add a string&#8221;, &#8220;close the &lt;title&gt; tag&#8221;, &#8220;open a &lt;p&gt;
tag&#8221;, and so on. Beautiful Soup offers tools for reconstructing the
initial parse of the document.</p>
<div class="section" id="next-element-and-previous-element">
<span id="element-generators"></span><h3><tt class="docutils literal"><span class="pre">.next_element</span></tt> and <tt class="docutils literal"><span class="pre">.previous_element</span></tt><a class="headerlink" href="index.html#next-element-and-previous-element" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">.next_element</span></tt> attribute of a string or tag points to whatever
was parsed immediately afterwards. It might be the same as
<tt class="docutils literal"><span class="pre">.next_sibling</span></tt>, but it&#8217;s usually drastically different.</p>
<p>Here&#8217;s the final &lt;a&gt; tag in the &#8220;three sisters&#8221; document. Its
<tt class="docutils literal"><span class="pre">.next_sibling</span></tt> is a string: the conclusion of the sentence that was
interrupted by the start of the &lt;a&gt; tag.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">last_a_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="s">&quot;link3&quot;</span><span class="p">)</span>
<span class="n">last_a_tag</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;</span>

<span class="n">last_a_tag</span><span class="o">.</span><span class="n">next_sibling</span>
<span class="c"># &#39;; and they lived at the bottom of a well.&#39;</span>
</pre></div>
</div>
<p>But the <tt class="docutils literal"><span class="pre">.next_element</span></tt> of that &lt;a&gt; tag, the thing that was parsed
immediately after the &lt;a&gt; tag, is <cite>not</cite> the rest of that sentence:
it&#8217;s the word &#8220;Tillie&#8221;:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">last_a_tag</span><span class="o">.</span><span class="n">next_element</span>
<span class="c"># u&#39;Tillie&#39;</span>
</pre></div>
</div>
<p>That&#8217;s because in the original markup, the word &#8220;Tillie&#8221; appeared
before that semicolon. The parser encountered an &lt;a&gt; tag, then the
word &#8220;Tillie&#8221;, then the closing &lt;/a&gt; tag, then the semicolon and rest of
the sentence. The semicolon is on the same level as the &lt;a&gt; tag, but the
word &#8220;Tillie&#8221; was encountered first.</p>
<p>The <tt class="docutils literal"><span class="pre">.previous_element</span></tt> attribute is the exact opposite of
<tt class="docutils literal"><span class="pre">.next_element</span></tt>. It points to whatever element was parsed
immediately before this one:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">last_a_tag</span><span class="o">.</span><span class="n">previous_element</span>
<span class="c"># u&#39; and\n&#39;</span>
<span class="n">last_a_tag</span><span class="o">.</span><span class="n">previous_element</span><span class="o">.</span><span class="n">next_element</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="next-elements-and-previous-elements">
<h3><tt class="docutils literal"><span class="pre">.next_elements</span></tt> and <tt class="docutils literal"><span class="pre">.previous_elements</span></tt><a class="headerlink" href="index.html#next-elements-and-previous-elements" title="Permalink to this headline">¶</a></h3>
<p>You should get the idea by now. You can use these iterators to move
forward or backward in the document as it was parsed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">last_a_tag</span><span class="o">.</span><span class="n">next_elements</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">element</span><span class="p">))</span>
<span class="c"># u&#39;Tillie&#39;</span>
<span class="c"># u&#39;;\nand they lived at the bottom of a well.&#39;</span>
<span class="c"># u&#39;\n\n&#39;</span>
<span class="c"># &lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
<span class="c"># u&#39;...&#39;</span>
<span class="c"># u&#39;\n&#39;</span>
<span class="c"># None</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="searching-the-tree">
<h1>Searching the tree<a class="headerlink" href="index.html#searching-the-tree" title="Permalink to this headline">¶</a></h1>
<p>Beautiful Soup defines a lot of methods for searching the parse tree,
but they&#8217;re all very similar. I&#8217;m going to spend a lot of time explaining
the two most popular methods: <tt class="docutils literal"><span class="pre">find()</span></tt> and <tt class="docutils literal"><span class="pre">find_all()</span></tt>. The other
methods take almost exactly the same arguments, so I&#8217;ll just cover
them briefly.</p>
<p>Once again, I&#8217;ll be using the &#8220;three sisters&#8221; document as an example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">html_doc</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span>
<span class="s">&lt;html&gt;&lt;head&gt;&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;&lt;/head&gt;</span>

<span class="s">&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;Once upon a time there were three little sisters; and their names were</span>
<span class="s">&lt;a href=&quot;http://example.com/elsie&quot; class=&quot;sister&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="s">&lt;a href=&quot;http://example.com/lacie&quot; class=&quot;sister&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt; and</span>
<span class="s">&lt;a href=&quot;http://example.com/tillie&quot; class=&quot;sister&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;;</span>
<span class="s">and they lived at the bottom of a well.&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
<span class="s">&quot;&quot;&quot;</span>

<span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">BeautifulSoup</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">)</span>
</pre></div>
</div>
<p>By passing in a filter to an argument like <tt class="docutils literal"><span class="pre">find_all()</span></tt>, you can
zoom in on the parts of the document you&#8217;re interested in.</p>
<div class="section" id="kinds-of-filters">
<h2>Kinds of filters<a class="headerlink" href="index.html#kinds-of-filters" title="Permalink to this headline">¶</a></h2>
<p>Before talking in detail about <tt class="docutils literal"><span class="pre">find_all()</span></tt> and similar methods, I
want to show examples of different filters you can pass into these
methods. These filters show up again and again, throughout the
search API. You can use them to filter based on a tag&#8217;s name,
on its attributes, on the text of a string, or on some combination of
these.</p>
<div class="section" id="a-string">
<span id="id8"></span><h3>A string<a class="headerlink" href="index.html#a-string" title="Permalink to this headline">¶</a></h3>
<p>The simplest filter is a string. Pass a string to a search method and
Beautiful Soup will perform a match against that exact string. This
code finds all the &lt;b&gt; tags in the document:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&#39;b&#39;</span><span class="p">)</span>
<span class="c"># [&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;]</span>
</pre></div>
</div>
<p>If you pass in a byte string, Beautiful Soup will assume the string is
encoded as UTF-8. You can avoid this by passing in a Unicode string instead.</p>
</div>
<div class="section" id="a-regular-expression">
<span id="id9"></span><h3>A regular expression<a class="headerlink" href="index.html#a-regular-expression" title="Permalink to this headline">¶</a></h3>
<p>If you pass in a regular expression object, Beautiful Soup will filter
against that regular expression using its <tt class="docutils literal"><span class="pre">match()</span></tt> method. This code
finds all the tags whose names start with the letter &#8220;b&#8221;; in this
case, the &lt;body&gt; tag and the &lt;b&gt; tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">re</span>
<span class="k">for</span> <span class="n">tag</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;^b&quot;</span><span class="p">)):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="c"># body</span>
<span class="c"># b</span>
</pre></div>
</div>
<p>This code finds all the tags whose names contain the letter &#8216;t&#8217;:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">tag</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;t&quot;</span><span class="p">)):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="c"># html</span>
<span class="c"># title</span>
</pre></div>
</div>
</div>
<div class="section" id="a-list">
<span id="id10"></span><h3>A list<a class="headerlink" href="index.html#a-list" title="Permalink to this headline">¶</a></h3>
<p>If you pass in a list, Beautiful Soup will allow a string match
against <cite>any</cite> item in that list. This code finds all the &lt;a&gt; tags
<cite>and</cite> all the &lt;b&gt; tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">([</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="s">&quot;b&quot;</span><span class="p">])</span>
<span class="c"># [&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="true">
<span id="the-value-true"></span><h3><tt class="docutils literal"><span class="pre">True</span></tt><a class="headerlink" href="index.html#true" title="Permalink to this headline">¶</a></h3>
<p>The value <tt class="docutils literal"><span class="pre">True</span></tt> matches everything it can. This code finds <cite>all</cite>
the tags in the document, but none of the text strings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">tag</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="bp">True</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="c"># html</span>
<span class="c"># head</span>
<span class="c"># title</span>
<span class="c"># body</span>
<span class="c"># p</span>
<span class="c"># b</span>
<span class="c"># p</span>
<span class="c"># a</span>
<span class="c"># a</span>
<span class="c"># a</span>
<span class="c"># p</span>
</pre></div>
</div>
</div>
<div class="section" id="a-function">
<h3>A function<a class="headerlink" href="index.html#a-function" title="Permalink to this headline">¶</a></h3>
<p>If none of the other matches work for you, define a function that
takes an element as its only argument. The function should return
<tt class="docutils literal"><span class="pre">True</span></tt> if the argument matches, and <tt class="docutils literal"><span class="pre">False</span></tt> otherwise.</p>
<p>Here&#8217;s a function that returns <tt class="docutils literal"><span class="pre">True</span></tt> if a tag defines the &#8220;class&#8221;
attribute but doesn&#8217;t define the &#8220;id&#8221; attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">has_class_but_no_id</span><span class="p">(</span><span class="n">tag</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">tag</span><span class="o">.</span><span class="n">has_attr</span><span class="p">(</span><span class="s">&#39;class&#39;</span><span class="p">)</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">tag</span><span class="o">.</span><span class="n">has_attr</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Pass this function into <tt class="docutils literal"><span class="pre">find_all()</span></tt> and you&#8217;ll pick up all the &lt;p&gt;
tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">has_class_but_no_id</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;,</span>
<span class="c">#  &lt;p class=&quot;story&quot;&gt;Once upon a time there were...&lt;/p&gt;,</span>
<span class="c">#  &lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;]</span>
</pre></div>
</div>
<p>This function only picks up the &lt;p&gt; tags. It doesn&#8217;t pick up the &lt;a&gt;
tags, because those tags define both &#8220;class&#8221; and &#8220;id&#8221;. It doesn&#8217;t pick
up tags like &lt;html&gt; and &lt;title&gt;, because those tags don&#8217;t define
&#8220;class&#8221;.</p>
<p>Here&#8217;s a function that returns <tt class="docutils literal"><span class="pre">True</span></tt> if a tag is surrounded by
string objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">NavigableString</span>
<span class="k">def</span> <span class="nf">surrounded_by_strings</span><span class="p">(</span><span class="n">tag</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">next_element</span><span class="p">,</span> <span class="n">NavigableString</span><span class="p">)</span>
            <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">previous_element</span><span class="p">,</span> <span class="n">NavigableString</span><span class="p">))</span>

<span class="k">for</span> <span class="n">tag</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">surrounded_by_strings</span><span class="p">):</span>
    <span class="k">print</span> <span class="n">tag</span><span class="o">.</span><span class="n">name</span>
<span class="c"># p</span>
<span class="c"># a</span>
<span class="c"># a</span>
<span class="c"># a</span>
<span class="c"># p</span>
</pre></div>
</div>
<p>Now we&#8217;re ready to look at the search methods in detail.</p>
</div>
</div>
<div class="section" id="find-all">
<h2><tt class="docutils literal"><span class="pre">find_all()</span></tt><a class="headerlink" href="index.html#find-all" title="Permalink to this headline">¶</a></h2>
<p>Signature: find_all(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id78"><em>recursive</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#limit"><em>limit</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>The <tt class="docutils literal"><span class="pre">find_all()</span></tt> method looks through a tag&#8217;s descendants and
retrieves <cite>all</cite> descendants that match your filters. I gave several
examples in <a class="reference internal" href="index.html#kinds-of-filters">Kinds of filters</a>, but here are a few more:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;link2&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;]</span>

<span class="kn">import</span> <span class="nn">re</span>
<span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;sisters&quot;</span><span class="p">))</span>
<span class="c"># u&#39;Once upon a time there were three little sisters; and their names were\n&#39;</span>
</pre></div>
</div>
<p>Some of these should look familiar, but others are new. What does it
mean to pass in a value for <tt class="docutils literal"><span class="pre">text</span></tt>, or <tt class="docutils literal"><span class="pre">id</span></tt>? Why does
<tt class="docutils literal"><span class="pre">find_all(&quot;p&quot;,</span> <span class="pre">&quot;title&quot;)</span></tt> find a &lt;p&gt; tag with the CSS class &#8220;title&#8221;?
Let&#8217;s look at the arguments to <tt class="docutils literal"><span class="pre">find_all()</span></tt>.</p>
<div class="section" id="the-name-argument">
<span id="id11"></span><h3>The <tt class="docutils literal"><span class="pre">name</span></tt> argument<a class="headerlink" href="index.html#the-name-argument" title="Permalink to this headline">¶</a></h3>
<p>Pass in a value for <tt class="docutils literal"><span class="pre">name</span></tt> and you&#8217;ll tell Beautiful Soup to only
consider tags with certain names. Text strings will be ignored, as
will tags whose names that don&#8217;t match.</p>
<p>This is the simplest usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>
</pre></div>
</div>
<p>Recall from <a class="reference internal" href="index.html#kinds-of-filters">Kinds of filters</a> that the value to <tt class="docutils literal"><span class="pre">name</span></tt> can be <a class="reference internal" href="index.html#a-string">a
string</a>, <a class="reference internal" href="index.html#a-regular-expression">a regular expression</a>, <a class="reference internal" href="index.html#a-list">a list</a>, <a class="reference internal" href="index.html#a-function">a function</a>, or <a class="reference internal" href="index.html#the-value-true">the value
True</a>.</p>
</div>
<div class="section" id="the-keyword-arguments">
<span id="kwargs"></span><h3>The keyword arguments<a class="headerlink" href="index.html#the-keyword-arguments" title="Permalink to this headline">¶</a></h3>
<p>Any argument that&#8217;s not recognized will be turned into a filter on one
of a tag&#8217;s attributes. If you pass in a value for an argument called <tt class="docutils literal"><span class="pre">id</span></tt>,
Beautiful Soup will filter against each tag&#8217;s &#8216;id&#8217; attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&#39;link2&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>If you pass in a value for <tt class="docutils literal"><span class="pre">href</span></tt>, Beautiful Soup will filter
against each tag&#8217;s &#8216;href&#8217; attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">href</span><span class="o">=</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;elsie&quot;</span><span class="p">))</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>You can filter an attribute based on <a class="reference internal" href="index.html#a-string">a string</a>, <a class="reference internal" href="index.html#a-regular-expression">a regular
expression</a>, <a class="reference internal" href="index.html#a-list">a list</a>, <a class="reference internal" href="index.html#a-function">a function</a>, or <a class="reference internal" href="index.html#the-value-true">the value True</a>.</p>
<p>This code finds all tags whose <tt class="docutils literal"><span class="pre">id</span></tt> attribute has a value,
regardless of what the value is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>You can filter multiple attributes at once by passing in more than one
keyword argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">href</span><span class="o">=</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;elsie&quot;</span><span class="p">),</span> <span class="nb">id</span><span class="o">=</span><span class="s">&#39;link1&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;three&lt;/a&gt;]</span>
</pre></div>
</div>
<p>Some attributes, like the data-* attributes in HTML 5, have names that
can&#8217;t be used as the names of keyword arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">data_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;div data-foo=&quot;value&quot;&gt;foo!&lt;/div&gt;&#39;</span><span class="p">)</span>
<span class="n">data_soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">data</span><span class="o">-</span><span class="n">foo</span><span class="o">=</span><span class="s">&quot;value&quot;</span><span class="p">)</span>
<span class="c"># SyntaxError: keyword can&#39;t be an expression</span>
</pre></div>
</div>
<p>You can use these attributes in searches by putting them into a
dictionary and passing the dictionary into <tt class="docutils literal"><span class="pre">find_all()</span></tt> as the
<tt class="docutils literal"><span class="pre">attrs</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">data_soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;data-foo&quot;</span><span class="p">:</span> <span class="s">&quot;value&quot;</span><span class="p">})</span>
<span class="c"># [&lt;div data-foo=&quot;value&quot;&gt;foo!&lt;/div&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="searching-by-css-class">
<span id="attrs"></span><h3>Searching by CSS class<a class="headerlink" href="index.html#searching-by-css-class" title="Permalink to this headline">¶</a></h3>
<p>It&#8217;s very useful to search for a tag that has a certain CSS class, but
the name of the CSS attribute, &#8220;class&#8221;, is a reserved word in
Python. Using <tt class="docutils literal"><span class="pre">class</span></tt> as a keyword argument will give you a syntax
error. As of Beautiful Soup 4.1.2, you can search by CSS class using
the keyword argument <tt class="docutils literal"><span class="pre">class_</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="n">class_</span><span class="o">=</span><span class="s">&quot;sister&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>As with any keyword argument, you can pass <tt class="docutils literal"><span class="pre">class_</span></tt> a string, a regular
expression, a function, or <tt class="docutils literal"><span class="pre">True</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">class_</span><span class="o">=</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;itl&quot;</span><span class="p">))</span>
<span class="c"># [&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;]</span>

<span class="k">def</span> <span class="nf">has_six_characters</span><span class="p">(</span><span class="n">css_class</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">css_class</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">css_class</span><span class="p">)</span> <span class="o">==</span> <span class="mi">6</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">class_</span><span class="o">=</span><span class="n">has_six_characters</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
<p><a class="reference internal" href="index.html#multivalue"><em>Remember</em></a> that a single tag can have multiple
values for its &#8220;class&#8221; attribute. When you search for a tag that
matches a certain CSS class, you&#8217;re matching against <cite>any</cite> of its CSS
classes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">css_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;&#39;</span><span class="p">)</span>
<span class="n">css_soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="n">class_</span><span class="o">=</span><span class="s">&quot;strikeout&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;]</span>

<span class="n">css_soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="n">class_</span><span class="o">=</span><span class="s">&quot;body&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;]</span>
</pre></div>
</div>
<p>You can also search for the exact string value of the <tt class="docutils literal"><span class="pre">class</span></tt> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">css_soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="n">class_</span><span class="o">=</span><span class="s">&quot;body strikeout&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;]</span>
</pre></div>
</div>
<p>But searching for variants of the string value won&#8217;t work:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">css_soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="n">class_</span><span class="o">=</span><span class="s">&quot;strikeout body&quot;</span><span class="p">)</span>
<span class="c"># []</span>
</pre></div>
</div>
<p>If you want to search for tags that match two or more CSS classes, you
should use a CSS selector:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">css_soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;p.strikeout.body&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;body strikeout&quot;&gt;&lt;/p&gt;]</span>
</pre></div>
</div>
<p>In older versions of Beautiful Soup, which don&#8217;t have the <tt class="docutils literal"><span class="pre">class_</span></tt>
shortcut, you can use the <tt class="docutils literal"><span class="pre">attrs</span></tt> trick mentioned above. Create a
dictionary whose value for &#8220;class&#8221; is the string (or regular
expression, or whatever) you want to search for:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;class&quot;</span><span class="p">:</span> <span class="s">&quot;sister&quot;</span><span class="p">})</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="the-text-argument">
<span id="text"></span><h3>The <tt class="docutils literal"><span class="pre">text</span></tt> argument<a class="headerlink" href="index.html#the-text-argument" title="Permalink to this headline">¶</a></h3>
<p>With <tt class="docutils literal"><span class="pre">text</span></tt> you can search for strings instead of tags. As with
<tt class="docutils literal"><span class="pre">name</span></tt> and the keyword arguments, you can pass in <a class="reference internal" href="index.html#a-string">a string</a>, <a class="reference internal" href="index.html#a-regular-expression">a
regular expression</a>, <a class="reference internal" href="index.html#a-list">a list</a>, <a class="reference internal" href="index.html#a-function">a function</a>, or <a class="reference internal" href="index.html#the-value-true">the value True</a>.
Here are some examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="s">&quot;Elsie&quot;</span><span class="p">)</span>
<span class="c"># [u&#39;Elsie&#39;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="p">[</span><span class="s">&quot;Tillie&quot;</span><span class="p">,</span> <span class="s">&quot;Elsie&quot;</span><span class="p">,</span> <span class="s">&quot;Lacie&quot;</span><span class="p">])</span>
<span class="c"># [u&#39;Elsie&#39;, u&#39;Lacie&#39;, u&#39;Tillie&#39;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">&quot;Dormouse&quot;</span><span class="p">))</span>
<span class="p">[</span><span class="s">u&quot;The Dormouse&#39;s story&quot;</span><span class="p">,</span> <span class="s">u&quot;The Dormouse&#39;s story&quot;</span><span class="p">]</span>

<span class="k">def</span> <span class="nf">is_the_only_string_within_a_tag</span><span class="p">(</span><span class="n">s</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Return True if this string is the only child of its parent tag.&quot;&quot;&quot;</span>
    <span class="k">return</span> <span class="p">(</span><span class="n">s</span> <span class="o">==</span> <span class="n">s</span><span class="o">.</span><span class="n">parent</span><span class="o">.</span><span class="n">string</span><span class="p">)</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">is_the_only_string_within_a_tag</span><span class="p">)</span>
<span class="c"># [u&quot;The Dormouse&#39;s story&quot;, u&quot;The Dormouse&#39;s story&quot;, u&#39;Elsie&#39;, u&#39;Lacie&#39;, u&#39;Tillie&#39;, u&#39;...&#39;]</span>
</pre></div>
</div>
<p>Although <tt class="docutils literal"><span class="pre">text</span></tt> is for finding strings, you can combine it with
arguments that find tags: Beautiful Soup will find all tags whose
<tt class="docutils literal"><span class="pre">.string</span></tt> matches your value for <tt class="docutils literal"><span class="pre">text</span></tt>. This code finds the &lt;a&gt;
tags whose <tt class="docutils literal"><span class="pre">.string</span></tt> is &#8220;Elsie&#8221;:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="s">&quot;Elsie&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a href=&quot;http://example.com/elsie&quot; class=&quot;sister&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="the-limit-argument">
<span id="limit"></span><h3>The <tt class="docutils literal"><span class="pre">limit</span></tt> argument<a class="headerlink" href="index.html#the-limit-argument" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">find_all()</span></tt> returns all the tags and strings that match your
filters. This can take a while if the document is large. If you don&#8217;t
need <cite>all</cite> the results, you can pass in a number for <tt class="docutils literal"><span class="pre">limit</span></tt>. This
works just like the LIMIT keyword in SQL. It tells Beautiful Soup to
stop gathering results after it&#8217;s found a certain number.</p>
<p>There are three links in the &#8220;three sisters&#8221; document, but this code
only finds the first two:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="the-recursive-argument">
<span id="recursive"></span><h3>The <tt class="docutils literal"><span class="pre">recursive</span></tt> argument<a class="headerlink" href="index.html#the-recursive-argument" title="Permalink to this headline">¶</a></h3>
<p>If you call <tt class="docutils literal"><span class="pre">mytag.find_all()</span></tt>, Beautiful Soup will examine all the
descendants of <tt class="docutils literal"><span class="pre">mytag</span></tt>: its children, its children&#8217;s children, and
so on. If you only want Beautiful Soup to consider direct children,
you can pass in <tt class="docutils literal"><span class="pre">recursive=False</span></tt>. See the difference here:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">html</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">html</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="c"># []</span>
</pre></div>
</div>
<p>Here&#8217;s that part of the document:</p>
<div class="highlight-python"><pre>&lt;html&gt;
 &lt;head&gt;
  &lt;title&gt;
   The Dormouse's story
  &lt;/title&gt;
 &lt;/head&gt;
...</pre>
</div>
<p>The &lt;title&gt; tag is beneath the &lt;html&gt; tag, but it&#8217;s not <cite>directly</cite>
beneath the &lt;html&gt; tag: the &lt;head&gt; tag is in the way. Beautiful Soup
finds the &lt;title&gt; tag when it&#8217;s allowed to look at all descendants of
the &lt;html&gt; tag, but when <tt class="docutils literal"><span class="pre">recursive=False</span></tt> restricts it to the
&lt;html&gt; tag&#8217;s immediate children, it finds nothing.</p>
<p>Beautiful Soup offers a lot of tree-searching methods (covered below),
and they mostly take the same arguments as <tt class="docutils literal"><span class="pre">find_all()</span></tt>: <tt class="docutils literal"><span class="pre">name</span></tt>,
<tt class="docutils literal"><span class="pre">attrs</span></tt>, <tt class="docutils literal"><span class="pre">text</span></tt>, <tt class="docutils literal"><span class="pre">limit</span></tt>, and the keyword arguments. But the
<tt class="docutils literal"><span class="pre">recursive</span></tt> argument is different: <tt class="docutils literal"><span class="pre">find_all()</span></tt> and <tt class="docutils literal"><span class="pre">find()</span></tt> are
the only methods that support it. Passing <tt class="docutils literal"><span class="pre">recursive=False</span></tt> into a
method like <tt class="docutils literal"><span class="pre">find_parents()</span></tt> wouldn&#8217;t be very useful.</p>
</div>
</div>
<div class="section" id="calling-a-tag-is-like-calling-find-all">
<h2>Calling a tag is like calling <tt class="docutils literal"><span class="pre">find_all()</span></tt><a class="headerlink" href="index.html#calling-a-tag-is-like-calling-find-all" title="Permalink to this headline">¶</a></h2>
<p>Because <tt class="docutils literal"><span class="pre">find_all()</span></tt> is the most popular method in the Beautiful
Soup search API, you can use a shortcut for it. If you treat the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object or a <tt class="docutils literal"><span class="pre">Tag</span></tt> object as though it were a
function, then it&#8217;s the same as calling <tt class="docutils literal"><span class="pre">find_all()</span></tt> on that
object. These two lines of code are equivalent:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>
<span class="n">soup</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>These two lines are also equivalent:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">title</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">title</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="find">
<h2><tt class="docutils literal"><span class="pre">find()</span></tt><a class="headerlink" href="index.html#find" title="Permalink to this headline">¶</a></h2>
<p>Signature: find(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id78"><em>recursive</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>The <tt class="docutils literal"><span class="pre">find_all()</span></tt> method scans the entire document looking for
results, but sometimes you only want to find one result. If you know a
document only has one &lt;body&gt; tag, it&#8217;s a waste of time to scan the
entire document looking for more. Rather than passing in <tt class="docutils literal"><span class="pre">limit=1</span></tt>
every time you call <tt class="docutils literal"><span class="pre">find_all</span></tt>, you can use the <tt class="docutils literal"><span class="pre">find()</span></tt>
method. These two lines of code are <cite>nearly</cite> equivalent:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="s">&#39;title&#39;</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&#39;title&#39;</span><span class="p">)</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
</pre></div>
</div>
<p>The only difference is that <tt class="docutils literal"><span class="pre">find_all()</span></tt> returns a list containing
the single result, and <tt class="docutils literal"><span class="pre">find()</span></tt> just returns the result.</p>
<p>If <tt class="docutils literal"><span class="pre">find_all()</span></tt> can&#8217;t find anything, it returns an empty list. If
<tt class="docutils literal"><span class="pre">find()</span></tt> can&#8217;t find anything, it returns <tt class="docutils literal"><span class="pre">None</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;nosuchtag&quot;</span><span class="p">))</span>
<span class="c"># None</span>
</pre></div>
</div>
<p>Remember the <tt class="docutils literal"><span class="pre">soup.head.title</span></tt> trick from <a class="reference internal" href="index.html#navigating-using-tag-names">Navigating using tag
names</a>? That trick works by repeatedly calling <tt class="docutils literal"><span class="pre">find()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">title</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;head&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="find-parents-and-find-parent">
<h2><tt class="docutils literal"><span class="pre">find_parents()</span></tt> and <tt class="docutils literal"><span class="pre">find_parent()</span></tt><a class="headerlink" href="index.html#find-parents-and-find-parent" title="Permalink to this headline">¶</a></h2>
<p>Signature: find_parents(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#limit"><em>limit</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>Signature: find_parent(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>I spent a lot of time above covering <tt class="docutils literal"><span class="pre">find_all()</span></tt> and
<tt class="docutils literal"><span class="pre">find()</span></tt>. The Beautiful Soup API defines ten other methods for
searching the tree, but don&#8217;t be afraid. Five of these methods are
basically the same as <tt class="docutils literal"><span class="pre">find_all()</span></tt>, and the other five are basically
the same as <tt class="docutils literal"><span class="pre">find()</span></tt>. The only differences are in what parts of the
tree they search.</p>
<p>First let&#8217;s consider <tt class="docutils literal"><span class="pre">find_parents()</span></tt> and
<tt class="docutils literal"><span class="pre">find_parent()</span></tt>. Remember that <tt class="docutils literal"><span class="pre">find_all()</span></tt> and <tt class="docutils literal"><span class="pre">find()</span></tt> work
their way down the tree, looking at tag&#8217;s descendants. These methods
do the opposite: they work their way <cite>up</cite> the tree, looking at a tag&#8217;s
(or a string&#8217;s) parents. Let&#8217;s try them out, starting from a string
buried deep in the &#8220;three daughters&#8221; document:</p>
<div class="highlight-python"><pre>a_string = soup.find(text="Lacie")
a_string
# u'Lacie'

a_string.find_parents("a")
# [&lt;a class="sister" href="http://example.com/lacie" id="link2"&gt;Lacie&lt;/a&gt;]

a_string.find_parent("p")
# &lt;p class="story"&gt;Once upon a time there were three little sisters; and their names were
#  &lt;a class="sister" href="http://example.com/elsie" id="link1"&gt;Elsie&lt;/a&gt;,
#  &lt;a class="sister" href="http://example.com/lacie" id="link2"&gt;Lacie&lt;/a&gt; and
#  &lt;a class="sister" href="http://example.com/tillie" id="link3"&gt;Tillie&lt;/a&gt;;
#  and they lived at the bottom of a well.&lt;/p&gt;

a_string.find_parents("p", class="title")
# []</pre>
</div>
<p>One of the three &lt;a&gt; tags is the direct parent of the string in
question, so our search finds it. One of the three &lt;p&gt; tags is an
indirect parent of the string, and our search finds that as
well. There&#8217;s a &lt;p&gt; tag with the CSS class &#8220;title&#8221; <cite>somewhere</cite> in the
document, but it&#8217;s not one of this string&#8217;s parents, so we can&#8217;t find
it with <tt class="docutils literal"><span class="pre">find_parents()</span></tt>.</p>
<p>You may have made the connection between <tt class="docutils literal"><span class="pre">find_parent()</span></tt> and
<tt class="docutils literal"><span class="pre">find_parents()</span></tt>, and the <a class="reference internal" href="index.html#parent">.parent</a> and <a class="reference internal" href="index.html#parents">.parents</a> attributes
mentioned earlier. The connection is very strong. These search methods
actually use <tt class="docutils literal"><span class="pre">.parents</span></tt> to iterate over all the parents, and check
each one against the provided filter to see if it matches.</p>
</div>
<div class="section" id="find-next-siblings-and-find-next-sibling">
<h2><tt class="docutils literal"><span class="pre">find_next_siblings()</span></tt> and <tt class="docutils literal"><span class="pre">find_next_sibling()</span></tt><a class="headerlink" href="index.html#find-next-siblings-and-find-next-sibling" title="Permalink to this headline">¶</a></h2>
<p>Signature: find_next_siblings(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#limit"><em>limit</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>Signature: find_next_sibling(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>These methods use <a class="reference internal" href="index.html#sibling-generators"><em>.next_siblings</em></a> to
iterate over the rest of an element&#8217;s siblings in the tree. The
<tt class="docutils literal"><span class="pre">find_next_siblings()</span></tt> method returns all the siblings that match,
and <tt class="docutils literal"><span class="pre">find_next_sibling()</span></tt> only returns the first one:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">first_link</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="n">first_link</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>

<span class="n">first_link</span><span class="o">.</span><span class="n">find_next_siblings</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">first_story_paragraph</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="s">&quot;story&quot;</span><span class="p">)</span>
<span class="n">first_story_paragraph</span><span class="o">.</span><span class="n">find_next_sibling</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">)</span>
<span class="c"># &lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="find-previous-siblings-and-find-previous-sibling">
<h2><tt class="docutils literal"><span class="pre">find_previous_siblings()</span></tt> and <tt class="docutils literal"><span class="pre">find_previous_sibling()</span></tt><a class="headerlink" href="index.html#find-previous-siblings-and-find-previous-sibling" title="Permalink to this headline">¶</a></h2>
<p>Signature: find_previous_siblings(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#limit"><em>limit</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>Signature: find_previous_sibling(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>These methods use <a class="reference internal" href="index.html#sibling-generators"><em>.previous_siblings</em></a> to iterate over an element&#8217;s
siblings that precede it in the tree. The <tt class="docutils literal"><span class="pre">find_previous_siblings()</span></tt>
method returns all the siblings that match, and
<tt class="docutils literal"><span class="pre">find_previous_sibling()</span></tt> only returns the first one:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">last_link</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="s">&quot;link3&quot;</span><span class="p">)</span>
<span class="n">last_link</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;</span>

<span class="n">last_link</span><span class="o">.</span><span class="n">find_previous_siblings</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>

<span class="n">first_story_paragraph</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">,</span> <span class="s">&quot;story&quot;</span><span class="p">)</span>
<span class="n">first_story_paragraph</span><span class="o">.</span><span class="n">find_previous_sibling</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">)</span>
<span class="c"># &lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="find-all-next-and-find-next">
<h2><tt class="docutils literal"><span class="pre">find_all_next()</span></tt> and <tt class="docutils literal"><span class="pre">find_next()</span></tt><a class="headerlink" href="index.html#find-all-next-and-find-next" title="Permalink to this headline">¶</a></h2>
<p>Signature: find_all_next(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#limit"><em>limit</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>Signature: find_next(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>These methods use <a class="reference internal" href="index.html#element-generators"><em>.next_elements</em></a> to
iterate over whatever tags and strings that come after it in the
document. The <tt class="docutils literal"><span class="pre">find_all_next()</span></tt> method returns all matches, and
<tt class="docutils literal"><span class="pre">find_next()</span></tt> only returns the first match:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">first_link</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="n">first_link</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>

<span class="n">first_link</span><span class="o">.</span><span class="n">find_all_next</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="c"># [u&#39;Elsie&#39;, u&#39;,\n&#39;, u&#39;Lacie&#39;, u&#39; and\n&#39;, u&#39;Tillie&#39;,</span>
<span class="c">#  u&#39;;\nand they lived at the bottom of a well.&#39;, u&#39;\n\n&#39;, u&#39;...&#39;, u&#39;\n&#39;]</span>

<span class="n">first_link</span><span class="o">.</span><span class="n">find_next</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">)</span>
<span class="c"># &lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
</pre></div>
</div>
<p>In the first example, the string &#8220;Elsie&#8221; showed up, even though it was
contained within the &lt;a&gt; tag we started from. In the second example,
the last &lt;p&gt; tag in the document showed up, even though it&#8217;s not in
the same part of the tree as the &lt;a&gt; tag we started from. For these
methods, all that matters is that an element match the filter, and
show up later in the document than the starting element.</p>
</div>
<div class="section" id="find-all-previous-and-find-previous">
<h2><tt class="docutils literal"><span class="pre">find_all_previous()</span></tt> and <tt class="docutils literal"><span class="pre">find_previous()</span></tt><a class="headerlink" href="index.html#find-all-previous-and-find-previous" title="Permalink to this headline">¶</a></h2>
<p>Signature: find_all_previous(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#limit"><em>limit</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>Signature: find_previous(<a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>)</p>
<p>These methods use <a class="reference internal" href="index.html#element-generators"><em>.previous_elements</em></a> to
iterate over the tags and strings that came before it in the
document. The <tt class="docutils literal"><span class="pre">find_all_previous()</span></tt> method returns all matches, and
<tt class="docutils literal"><span class="pre">find_previous()</span></tt> only returns the first match:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">first_link</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="n">first_link</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;</span>

<span class="n">first_link</span><span class="o">.</span><span class="n">find_all_previous</span><span class="p">(</span><span class="s">&quot;p&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;story&quot;&gt;Once upon a time there were three little sisters; ...&lt;/p&gt;,</span>
<span class="c">#  &lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;]</span>

<span class="n">first_link</span><span class="o">.</span><span class="n">find_previous</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># &lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;</span>
</pre></div>
</div>
<p>The call to <tt class="docutils literal"><span class="pre">find_all_previous(&quot;p&quot;)</span></tt> found the first paragraph in
the document (the one with class=&#8221;title&#8221;), but it also finds the
second paragraph, the &lt;p&gt; tag that contains the &lt;a&gt; tag we started
with. This shouldn&#8217;t be too surprising: we&#8217;re looking at all the tags
that show up earlier in the document than the one we started with. A
&lt;p&gt; tag that contains an &lt;a&gt; tag must have shown up before the &lt;a&gt;
tag it contains.</p>
</div>
<div class="section" id="css-selectors">
<h2>CSS selectors<a class="headerlink" href="index.html#css-selectors" title="Permalink to this headline">¶</a></h2>
<p>Beautiful Soup supports the most commonly-used CSS selectors. Just
pass a string into the <tt class="docutils literal"><span class="pre">.select()</span></tt> method of a <tt class="docutils literal"><span class="pre">Tag</span></tt> object or the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object itself.</p>
<p>You can find tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;p nth-of-type(3)&quot;</span><span class="p">)</span>
<span class="c"># [&lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;]</span>
</pre></div>
</div>
<p>Find tags beneath other tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;body a&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot;  id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;html head title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>
</pre></div>
</div>
<p>Find tags <cite>directly</cite> beneath other tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;head &gt; title&quot;</span><span class="p">)</span>
<span class="c"># [&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;p &gt; a&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot;  id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;p &gt; a:nth-of-type(2)&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;p &gt; #link1&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;body &gt; a&quot;</span><span class="p">)</span>
<span class="c"># []</span>
</pre></div>
</div>
<p>Find the siblings of tags:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;#link1 ~ .sister&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot;  id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;#link1 + .sister&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>Find tags by CSS class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;.sister&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;[class~=sister]&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>Find tags by ID:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;#link1&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&quot;a#link2&quot;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>Test for the existence of an attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&#39;a[href]&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>Find tags by attribute value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&#39;a[href=&quot;http://example.com/elsie&quot;]&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&#39;a[href^=&quot;http://example.com/&quot;]&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt;,</span>
<span class="c">#  &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&#39;a[href$=&quot;tillie&quot;]&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;]</span>

<span class="n">soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&#39;a[href*=&quot;.com/el&quot;]&#39;</span><span class="p">)</span>
<span class="c"># [&lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;]</span>
</pre></div>
</div>
<p>Match language codes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">multilingual_markup</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span>
<span class="s"> &lt;p lang=&quot;en&quot;&gt;Hello&lt;/p&gt;</span>
<span class="s"> &lt;p lang=&quot;en-us&quot;&gt;Howdy, y&#39;all&lt;/p&gt;</span>
<span class="s"> &lt;p lang=&quot;en-gb&quot;&gt;Pip-pip, old fruit&lt;/p&gt;</span>
<span class="s"> &lt;p lang=&quot;fr&quot;&gt;Bonjour mes amis&lt;/p&gt;</span>
<span class="s">&quot;&quot;&quot;</span>
<span class="n">multilingual_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">multilingual_markup</span><span class="p">)</span>
<span class="n">multilingual_soup</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="s">&#39;p[lang|=en]&#39;</span><span class="p">)</span>
<span class="c"># [&lt;p lang=&quot;en&quot;&gt;Hello&lt;/p&gt;,</span>
<span class="c">#  &lt;p lang=&quot;en-us&quot;&gt;Howdy, y&#39;all&lt;/p&gt;,</span>
<span class="c">#  &lt;p lang=&quot;en-gb&quot;&gt;Pip-pip, old fruit&lt;/p&gt;]</span>
</pre></div>
</div>
<p>This is a convenience for users who know the CSS selector syntax. You
can do all this stuff with the Beautiful Soup API. And if CSS
selectors are all you need, you might as well use lxml directly: it&#8217;s
a lot faster, and it supports more CSS selectors. But this lets you
<cite>combine</cite> simple CSS selectors with the Beautiful Soup API.</p>
</div>
</div>
<div class="section" id="modifying-the-tree">
<h1>Modifying the tree<a class="headerlink" href="index.html#modifying-the-tree" title="Permalink to this headline">¶</a></h1>
<p>Beautiful Soup&#8217;s main strength is in searching the parse tree, but you
can also modify the tree and write your changes as a new HTML or XML
document.</p>
<div class="section" id="changing-tag-names-and-attributes">
<h2>Changing tag names and attributes<a class="headerlink" href="index.html#changing-tag-names-and-attributes" title="Permalink to this headline">¶</a></h2>
<p>I covered this earlier, in <a class="reference internal" href="index.html#attributes">Attributes</a>, but it bears repeating. You
can rename a tag, change the values of its attributes, add new
attributes, and delete attributes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;b class=&quot;boldest&quot;&gt;Extremely bold&lt;/b&gt;&#39;</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">b</span>

<span class="n">tag</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="s">&quot;blockquote&quot;</span>
<span class="n">tag</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s">&#39;verybold&#39;</span>
<span class="n">tag</span><span class="p">[</span><span class="s">&#39;id&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">tag</span>
<span class="c"># &lt;blockquote class=&quot;verybold&quot; id=&quot;1&quot;&gt;Extremely bold&lt;/blockquote&gt;</span>

<span class="k">del</span> <span class="n">tag</span><span class="p">[</span><span class="s">&#39;class&#39;</span><span class="p">]</span>
<span class="k">del</span> <span class="n">tag</span><span class="p">[</span><span class="s">&#39;id&#39;</span><span class="p">]</span>
<span class="n">tag</span>
<span class="c"># &lt;blockquote&gt;Extremely bold&lt;/blockquote&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="modifying-string">
<h2>Modifying <tt class="docutils literal"><span class="pre">.string</span></tt><a class="headerlink" href="index.html#modifying-string" title="Permalink to this headline">¶</a></h2>
<p>If you set a tag&#8217;s <tt class="docutils literal"><span class="pre">.string</span></tt> attribute, the tag&#8217;s contents are
replaced with the string you give:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>

<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="n">tag</span><span class="o">.</span><span class="n">string</span> <span class="o">=</span> <span class="s">&quot;New link text.&quot;</span>
<span class="n">tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;New link text.&lt;/a&gt;</span>
</pre></div>
</div>
<p>Be careful: if the tag contained other tags, they and all their
contents will be destroyed.</p>
</div>
<div class="section" id="append">
<h2><tt class="docutils literal"><span class="pre">append()</span></tt><a class="headerlink" href="index.html#append" title="Permalink to this headline">¶</a></h2>
<p>You can add to a tag&#8217;s contents with <tt class="docutils literal"><span class="pre">Tag.append()</span></tt>. It works just
like calling <tt class="docutils literal"><span class="pre">.append()</span></tt> on a Python list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;Foo&lt;/a&gt;&quot;</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;Bar&quot;</span><span class="p">)</span>

<span class="n">soup</span>
<span class="c"># &lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;a&gt;FooBar&lt;/a&gt;&lt;/body&gt;&lt;/html&gt;</span>
<span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [u&#39;Foo&#39;, u&#39;Bar&#39;]</span>
</pre></div>
</div>
</div>
<div class="section" id="beautifulsoup-new-string-and-new-tag">
<h2><tt class="docutils literal"><span class="pre">BeautifulSoup.new_string()</span></tt> and <tt class="docutils literal"><span class="pre">.new_tag()</span></tt><a class="headerlink" href="index.html#beautifulsoup-new-string-and-new-tag" title="Permalink to this headline">¶</a></h2>
<p>If you need to add a string to a document, no problem&#8211;you can pass a
Python string in to <tt class="docutils literal"><span class="pre">append()</span></tt>, or you can call the factory method
<tt class="docutils literal"><span class="pre">BeautifulSoup.new_string()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;b&gt;&lt;/b&gt;&quot;</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">b</span>
<span class="n">tag</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;Hello&quot;</span><span class="p">)</span>
<span class="n">new_string</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">new_string</span><span class="p">(</span><span class="s">&quot; there&quot;</span><span class="p">)</span>
<span class="n">tag</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">new_string</span><span class="p">)</span>
<span class="n">tag</span>
<span class="c"># &lt;b&gt;Hello there.&lt;/b&gt;</span>
<span class="n">tag</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [u&#39;Hello&#39;, u&#39; there&#39;]</span>
</pre></div>
</div>
<p>If you want to create a comment or some other subclass of
<tt class="docutils literal"><span class="pre">NavigableString</span></tt>, pass that class as the second argument to
<tt class="docutils literal"><span class="pre">new_string()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">Comment</span>
<span class="n">new_comment</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">new_string</span><span class="p">(</span><span class="s">&quot;Nice to see you.&quot;</span><span class="p">,</span> <span class="n">Comment</span><span class="p">)</span>
<span class="n">tag</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">new_comment</span><span class="p">)</span>
<span class="n">tag</span>
<span class="c"># &lt;b&gt;Hello there&lt;!--Nice to see you.--&gt;&lt;/b&gt;</span>
<span class="n">tag</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [u&#39;Hello&#39;, u&#39; there&#39;, u&#39;Nice to see you.&#39;]</span>
</pre></div>
</div>
<p>(This is a new feature in Beautiful Soup 4.2.1.)</p>
<p>What if you need to create a whole new tag?  The best solution is to
call the factory method <tt class="docutils literal"><span class="pre">BeautifulSoup.new_tag()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;b&gt;&lt;/b&gt;&quot;</span><span class="p">)</span>
<span class="n">original_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">b</span>

<span class="n">new_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">new_tag</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">,</span> <span class="n">href</span><span class="o">=</span><span class="s">&quot;http://www.example.com&quot;</span><span class="p">)</span>
<span class="n">original_tag</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">new_tag</span><span class="p">)</span>
<span class="n">original_tag</span>
<span class="c"># &lt;b&gt;&lt;a href=&quot;http://www.example.com&quot;&gt;&lt;/a&gt;&lt;/b&gt;</span>

<span class="n">new_tag</span><span class="o">.</span><span class="n">string</span> <span class="o">=</span> <span class="s">&quot;Link text.&quot;</span>
<span class="n">original_tag</span>
<span class="c"># &lt;b&gt;&lt;a href=&quot;http://www.example.com&quot;&gt;Link text.&lt;/a&gt;&lt;/b&gt;</span>
</pre></div>
</div>
<p>Only the first argument, the tag name, is required.</p>
</div>
<div class="section" id="insert">
<h2><tt class="docutils literal"><span class="pre">insert()</span></tt><a class="headerlink" href="index.html#insert" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">Tag.insert()</span></tt> is just like <tt class="docutils literal"><span class="pre">Tag.append()</span></tt>, except the new element
doesn&#8217;t necessarily go at the end of its parent&#8217;s
<tt class="docutils literal"><span class="pre">.contents</span></tt>. It&#8217;ll be inserted at whatever numeric position you
say. It works just like <tt class="docutils literal"><span class="pre">.insert()</span></tt> on a Python list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>

<span class="n">tag</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">&quot;but did not endorse &quot;</span><span class="p">)</span>
<span class="n">tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;I linked to but did not endorse &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;</span>
<span class="n">tag</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [u&#39;I linked to &#39;, u&#39;but did not endorse&#39;, &lt;i&gt;example.com&lt;/i&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="insert-before-and-insert-after">
<h2><tt class="docutils literal"><span class="pre">insert_before()</span></tt> and <tt class="docutils literal"><span class="pre">insert_after()</span></tt><a class="headerlink" href="index.html#insert-before-and-insert-after" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">insert_before()</span></tt> method inserts a tag or string immediately
before something else in the parse tree:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;b&gt;stop&lt;/b&gt;&quot;</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">new_tag</span><span class="p">(</span><span class="s">&quot;i&quot;</span><span class="p">)</span>
<span class="n">tag</span><span class="o">.</span><span class="n">string</span> <span class="o">=</span> <span class="s">&quot;Don&#39;t&quot;</span>
<span class="n">soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">string</span><span class="o">.</span><span class="n">insert_before</span><span class="p">(</span><span class="n">tag</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">b</span>
<span class="c"># &lt;b&gt;&lt;i&gt;Don&#39;t&lt;/i&gt;stop&lt;/b&gt;</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">insert_after()</span></tt> method moves a tag or string so that it
immediately follows something else in the parse tree:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">i</span><span class="o">.</span><span class="n">insert_after</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">new_string</span><span class="p">(</span><span class="s">&quot; ever &quot;</span><span class="p">))</span>
<span class="n">soup</span><span class="o">.</span><span class="n">b</span>
<span class="c"># &lt;b&gt;&lt;i&gt;Don&#39;t&lt;/i&gt; ever stop&lt;/b&gt;</span>
<span class="n">soup</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">contents</span>
<span class="c"># [&lt;i&gt;Don&#39;t&lt;/i&gt;, u&#39; ever &#39;, u&#39;stop&#39;]</span>
</pre></div>
</div>
</div>
<div class="section" id="clear">
<h2><tt class="docutils literal"><span class="pre">clear()</span></tt><a class="headerlink" href="index.html#clear" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">Tag.clear()</span></tt> removes the contents of a tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>

<span class="n">tag</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>
<span class="n">tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;&lt;/a&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="extract">
<h2><tt class="docutils literal"><span class="pre">extract()</span></tt><a class="headerlink" href="index.html#extract" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">PageElement.extract()</span></tt> removes a tag or string from the tree. It
returns the tag or string that was extracted:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">a_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>

<span class="n">i_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">i</span><span class="o">.</span><span class="n">extract</span><span class="p">()</span>

<span class="n">a_tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;I linked to&lt;/a&gt;</span>

<span class="n">i_tag</span>
<span class="c"># &lt;i&gt;example.com&lt;/i&gt;</span>

<span class="k">print</span><span class="p">(</span><span class="n">i_tag</span><span class="o">.</span><span class="n">parent</span><span class="p">)</span>
<span class="bp">None</span>
</pre></div>
</div>
<p>At this point you effectively have two parse trees: one rooted at the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object you used to parse the document, and one rooted
at the tag that was extracted. You can go on to call <tt class="docutils literal"><span class="pre">extract</span></tt> on
a child of the element you extracted:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">my_string</span> <span class="o">=</span> <span class="n">i_tag</span><span class="o">.</span><span class="n">string</span><span class="o">.</span><span class="n">extract</span><span class="p">()</span>
<span class="n">my_string</span>
<span class="c"># u&#39;example.com&#39;</span>

<span class="k">print</span><span class="p">(</span><span class="n">my_string</span><span class="o">.</span><span class="n">parent</span><span class="p">)</span>
<span class="c"># None</span>
<span class="n">i_tag</span>
<span class="c"># &lt;i&gt;&lt;/i&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="decompose">
<h2><tt class="docutils literal"><span class="pre">decompose()</span></tt><a class="headerlink" href="index.html#decompose" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">Tag.decompose()</span></tt> removes a tag from the tree, then <cite>completely
destroys it and its contents</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">a_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>

<span class="n">soup</span><span class="o">.</span><span class="n">i</span><span class="o">.</span><span class="n">decompose</span><span class="p">()</span>

<span class="n">a_tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;I linked to&lt;/a&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="replace-with">
<span id="id12"></span><h2><tt class="docutils literal"><span class="pre">replace_with()</span></tt><a class="headerlink" href="index.html#replace-with" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">PageElement.replace_with()</span></tt> removes a tag or string from the tree,
and replaces it with the tag or string of your choice:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">a_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>

<span class="n">new_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">new_tag</span><span class="p">(</span><span class="s">&quot;b&quot;</span><span class="p">)</span>
<span class="n">new_tag</span><span class="o">.</span><span class="n">string</span> <span class="o">=</span> <span class="s">&quot;example.net&quot;</span>
<span class="n">a_tag</span><span class="o">.</span><span class="n">i</span><span class="o">.</span><span class="n">replace_with</span><span class="p">(</span><span class="n">new_tag</span><span class="p">)</span>

<span class="n">a_tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;b&gt;example.net&lt;/b&gt;&lt;/a&gt;</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">replace_with()</span></tt> returns the tag or string that was replaced, so
that you can examine it or add it back to another part of the tree.</p>
</div>
<div class="section" id="wrap">
<h2><tt class="docutils literal"><span class="pre">wrap()</span></tt><a class="headerlink" href="index.html#wrap" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">PageElement.wrap()</span></tt> wraps an element in the tag you specify. It
returns the new wrapper:</p>
<div class="highlight-python"><pre>soup = BeautifulSoup("&lt;p&gt;I wish I was bold.&lt;/p&gt;")
soup.p.string.wrap(soup.new_tag("b"))
# &lt;b&gt;I wish I was bold.&lt;/b&gt;

soup.p.wrap(soup.new_tag("div")
# &lt;div&gt;&lt;p&gt;&lt;b&gt;I wish I was bold.&lt;/b&gt;&lt;/p&gt;&lt;/div&gt;</pre>
</div>
<p>This method is new in Beautiful Soup 4.0.5.</p>
</div>
<div class="section" id="unwrap">
<h2><tt class="docutils literal"><span class="pre">unwrap()</span></tt><a class="headerlink" href="index.html#unwrap" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">Tag.unwrap()</span></tt> is the opposite of <tt class="docutils literal"><span class="pre">wrap()</span></tt>. It replaces a tag with
whatever&#8217;s inside that tag. It&#8217;s good for stripping out markup:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">a_tag</span> <span class="o">=</span> <span class="n">soup</span><span class="o">.</span><span class="n">a</span>

<span class="n">a_tag</span><span class="o">.</span><span class="n">i</span><span class="o">.</span><span class="n">unwrap</span><span class="p">()</span>
<span class="n">a_tag</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;I linked to example.com&lt;/a&gt;</span>
</pre></div>
</div>
<p>Like <tt class="docutils literal"><span class="pre">replace_with()</span></tt>, <tt class="docutils literal"><span class="pre">unwrap()</span></tt> returns the tag
that was replaced.</p>
</div>
</div>
<div class="section" id="output">
<h1>Output<a class="headerlink" href="index.html#output" title="Permalink to this headline">¶</a></h1>
<div class="section" id="pretty-printing">
<span id="prettyprinting"></span><h2>Pretty-printing<a class="headerlink" href="index.html#pretty-printing" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">prettify()</span></tt> method will turn a Beautiful Soup parse tree into a
nicely formatted Unicode string, with each HTML/XML tag on its own line:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">()</span>
<span class="c"># &#39;&lt;html&gt;\n &lt;head&gt;\n &lt;/head&gt;\n &lt;body&gt;\n  &lt;a href=&quot;http://example.com/&quot;&gt;\n...&#39;</span>

<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;head&gt;</span>
<span class="c">#  &lt;/head&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;a href=&quot;http://example.com/&quot;&gt;</span>
<span class="c">#    I linked to</span>
<span class="c">#    &lt;i&gt;</span>
<span class="c">#     example.com</span>
<span class="c">#    &lt;/i&gt;</span>
<span class="c">#   &lt;/a&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>You can call <tt class="docutils literal"><span class="pre">prettify()</span></tt> on the top-level <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object,
or on any of its <tt class="docutils literal"><span class="pre">Tag</span></tt> objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;a href=&quot;http://example.com/&quot;&gt;</span>
<span class="c">#  I linked to</span>
<span class="c">#  &lt;i&gt;</span>
<span class="c">#   example.com</span>
<span class="c">#  &lt;/i&gt;</span>
<span class="c"># &lt;/a&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="non-pretty-printing">
<h2>Non-pretty printing<a class="headerlink" href="index.html#non-pretty-printing" title="Permalink to this headline">¶</a></h2>
<p>If you just want a string, with no fancy formatting, you can call
<tt class="docutils literal"><span class="pre">unicode()</span></tt> or <tt class="docutils literal"><span class="pre">str()</span></tt> on a <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object, or a <tt class="docutils literal"><span class="pre">Tag</span></tt>
within it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">str</span><span class="p">(</span><span class="n">soup</span><span class="p">)</span>
<span class="c"># &#39;&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&lt;/body&gt;&lt;/html&gt;&#39;</span>

<span class="nb">unicode</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="c"># u&#39;&lt;a href=&quot;http://example.com/&quot;&gt;I linked to &lt;i&gt;example.com&lt;/i&gt;&lt;/a&gt;&#39;</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">str()</span></tt> function returns a string encoded in UTF-8. See
<a class="reference internal" href="index.html#encodings">Encodings</a> for other options.</p>
<p>You can also call <tt class="docutils literal"><span class="pre">encode()</span></tt> to get a bytestring, and <tt class="docutils literal"><span class="pre">decode()</span></tt>
to get Unicode.</p>
</div>
<div class="section" id="output-formatters">
<span id="id13"></span><h2>Output formatters<a class="headerlink" href="index.html#output-formatters" title="Permalink to this headline">¶</a></h2>
<p>If you give Beautiful Soup a document that contains HTML entities like
&#8220;&amp;lquot;&#8221;, they&#8217;ll be converted to Unicode characters:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&amp;ldquo;Dammit!&amp;rdquo; he said.&quot;</span><span class="p">)</span>
<span class="nb">unicode</span><span class="p">(</span><span class="n">soup</span><span class="p">)</span>
<span class="c"># u&#39;&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;\u201cDammit!\u201d he said.&lt;/body&gt;&lt;/html&gt;&#39;</span>
</pre></div>
</div>
<p>If you then convert the document to a string, the Unicode characters
will be encoded as UTF-8. You won&#8217;t get the HTML entities back:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">str</span><span class="p">(</span><span class="n">soup</span><span class="p">)</span>
<span class="c"># &#39;&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;\xe2\x80\x9cDammit!\xe2\x80\x9d he said.&lt;/body&gt;&lt;/html&gt;&#39;</span>
</pre></div>
</div>
<p>By default, the only characters that are escaped upon output are bare
ampersands and angle brackets. These get turned into &#8220;&amp;amp;&#8221;, &#8220;&amp;lt;&#8221;,
and &#8220;&amp;gt;&#8221;, so that Beautiful Soup doesn&#8217;t inadvertently generate
invalid HTML or XML:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;p&gt;The law firm of Dewey, Cheatem, &amp; Howe&lt;/p&gt;&quot;</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">p</span>
<span class="c"># &lt;p&gt;The law firm of Dewey, Cheatem, &amp;amp; Howe&lt;/p&gt;</span>

<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;a href=&quot;http://example.com/?foo=val1&amp;bar=val2&quot;&gt;A link&lt;/a&gt;&#39;</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">a</span>
<span class="c"># &lt;a href=&quot;http://example.com/?foo=val1&amp;amp;bar=val2&quot;&gt;A link&lt;/a&gt;</span>
</pre></div>
</div>
<p>You can change this behavior by providing a value for the
<tt class="docutils literal"><span class="pre">formatter</span></tt> argument to <tt class="docutils literal"><span class="pre">prettify()</span></tt>, <tt class="docutils literal"><span class="pre">encode()</span></tt>, or
<tt class="docutils literal"><span class="pre">decode()</span></tt>. Beautiful Soup recognizes four possible values for
<tt class="docutils literal"><span class="pre">formatter</span></tt>.</p>
<p>The default is <tt class="docutils literal"><span class="pre">formatter=&quot;minimal&quot;</span></tt>. Strings will only be processed
enough to ensure that Beautiful Soup generates valid HTML/XML:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">french</span> <span class="o">=</span> <span class="s">&quot;&lt;p&gt;Il a dit &amp;lt;&amp;lt;Sacr&amp;eacute; bleu!&amp;gt;&amp;gt;&lt;/p&gt;&quot;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">french</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="s">&quot;minimal&quot;</span><span class="p">))</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p&gt;</span>
<span class="c">#    Il a dit &amp;lt;&amp;lt;Sacré bleu!&amp;gt;&amp;gt;</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>If you pass in <tt class="docutils literal"><span class="pre">formatter=&quot;html&quot;</span></tt>, Beautiful Soup will convert
Unicode characters to HTML entities whenever possible:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="s">&quot;html&quot;</span><span class="p">))</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p&gt;</span>
<span class="c">#    Il a dit &amp;lt;&amp;lt;Sacr&amp;eacute; bleu!&amp;gt;&amp;gt;</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>If you pass in <tt class="docutils literal"><span class="pre">formatter=None</span></tt>, Beautiful Soup will not modify
strings at all on output. This is the fastest option, but it may lead
to Beautiful Soup generating invalid HTML/XML, as in these examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="bp">None</span><span class="p">))</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p&gt;</span>
<span class="c">#    Il a dit &lt;&lt;Sacré bleu!&gt;&gt;</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>

<span class="n">link_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&#39;&lt;a href=&quot;http://example.com/?foo=val1&amp;bar=val2&quot;&gt;A link&lt;/a&gt;&#39;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">link_soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="bp">None</span><span class="p">))</span>
<span class="c"># &lt;a href=&quot;http://example.com/?foo=val1&amp;bar=val2&quot;&gt;A link&lt;/a&gt;</span>
</pre></div>
</div>
<p>Finally, if you pass in a function for <tt class="docutils literal"><span class="pre">formatter</span></tt>, Beautiful Soup
will call that function once for every string and attribute value in
the document. You can do whatever you want in this function. Here&#8217;s a
formatter that converts strings to uppercase and does absolutely
nothing else:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">uppercase</span><span class="p">(</span><span class="nb">str</span><span class="p">):</span>
    <span class="k">return</span> <span class="nb">str</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>

<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="n">uppercase</span><span class="p">))</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p&gt;</span>
<span class="c">#    IL A DIT &lt;&lt;SACRÉ BLEU!&gt;&gt;</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>

<span class="k">print</span><span class="p">(</span><span class="n">link_soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="n">uppercase</span><span class="p">))</span>
<span class="c"># &lt;a href=&quot;HTTP://EXAMPLE.COM/?FOO=VAL1&amp;BAR=VAL2&quot;&gt;</span>
<span class="c">#  A LINK</span>
<span class="c"># &lt;/a&gt;</span>
</pre></div>
</div>
<p>If you&#8217;re writing your own function, you should know about the
<tt class="docutils literal"><span class="pre">EntitySubstitution</span></tt> class in the <tt class="docutils literal"><span class="pre">bs4.dammit</span></tt> module. This class
implements Beautiful Soup&#8217;s standard formatters as class methods: the
&#8220;html&#8221; formatter is <tt class="docutils literal"><span class="pre">EntitySubstitution.substitute_html</span></tt>, and the
&#8220;minimal&#8221; formatter is <tt class="docutils literal"><span class="pre">EntitySubstitution.substitute_xml</span></tt>. You can
use these functions to simulate <tt class="docutils literal"><span class="pre">formatter=html</span></tt> or
<tt class="docutils literal"><span class="pre">formatter==minimal</span></tt>, but then do something extra.</p>
<p>Here&#8217;s an example that replaces Unicode characters with HTML entities
whenever possible, but <cite>also</cite> converts all strings to uppercase:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4.dammit</span> <span class="kn">import</span> <span class="n">EntitySubstitution</span>
<span class="k">def</span> <span class="nf">uppercase_and_substitute_html_entities</span><span class="p">(</span><span class="nb">str</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">EntitySubstitution</span><span class="o">.</span><span class="n">substitute_html</span><span class="p">(</span><span class="nb">str</span><span class="o">.</span><span class="n">upper</span><span class="p">())</span>

<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="n">uppercase_and_substitute_html_entities</span><span class="p">))</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p&gt;</span>
<span class="c">#    IL A DIT &amp;lt;&amp;lt;SACR&amp;Eacute; BLEU!&amp;gt;&amp;gt;</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>One last caveat: if you create a <tt class="docutils literal"><span class="pre">CData</span></tt> object, the text inside
that object is always presented <cite>exactly as it appears, with no
formatting</cite>. Beautiful Soup will call the formatter method, just in
case you&#8217;ve written a custom method that counts all the strings in the
document or something, but it will ignore the return value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4.element</span> <span class="kn">import</span> <span class="n">CData</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;/a&gt;&quot;</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">string</span> <span class="o">=</span> <span class="n">CData</span><span class="p">(</span><span class="s">&quot;one &lt; three&quot;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="n">formatter</span><span class="o">=</span><span class="s">&quot;xml&quot;</span><span class="p">))</span>
<span class="c"># &lt;a&gt;</span>
<span class="c">#  &lt;![CDATA[one &lt; three]]&gt;</span>
<span class="c"># &lt;/a&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="get-text">
<h2><tt class="docutils literal"><span class="pre">get_text()</span></tt><a class="headerlink" href="index.html#get-text" title="Permalink to this headline">¶</a></h2>
<p>If you only want the text part of a document or tag, you can use the
<tt class="docutils literal"><span class="pre">get_text()</span></tt> method. It returns all the text in a document or
beneath a tag, as a single Unicode string:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&#39;&lt;a href=&quot;http://example.com/&quot;&gt;</span><span class="se">\n</span><span class="s">I linked to &lt;i&gt;example.com&lt;/i&gt;</span><span class="se">\n</span><span class="s">&lt;/a&gt;&#39;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>

<span class="n">soup</span><span class="o">.</span><span class="n">get_text</span><span class="p">()</span>
<span class="s">u&#39;</span><span class="se">\n</span><span class="s">I linked to example.com</span><span class="se">\n</span><span class="s">&#39;</span>
<span class="n">soup</span><span class="o">.</span><span class="n">i</span><span class="o">.</span><span class="n">get_text</span><span class="p">()</span>
<span class="s">u&#39;example.com&#39;</span>
</pre></div>
</div>
<p>You can specify a string to be used to join the bits of text
together:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># soup.get_text(&quot;|&quot;)</span>
<span class="s">u&#39;</span><span class="se">\n</span><span class="s">I linked to |example.com|</span><span class="se">\n</span><span class="s">&#39;</span>
</pre></div>
</div>
<p>You can tell Beautiful Soup to strip whitespace from the beginning and
end of each bit of text:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># soup.get_text(&quot;|&quot;, strip=True)</span>
<span class="s">u&#39;I linked to|example.com&#39;</span>
</pre></div>
</div>
<p>But at that point you might want to use the <a class="reference internal" href="index.html#string-generators"><em>.stripped_strings</em></a>
generator instead, and process the text yourself:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">text</span> <span class="k">for</span> <span class="n">text</span> <span class="ow">in</span> <span class="n">soup</span><span class="o">.</span><span class="n">stripped_strings</span><span class="p">]</span>
<span class="c"># [u&#39;I linked to&#39;, u&#39;example.com&#39;]</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="specifying-the-parser-to-use">
<h1>Specifying the parser to use<a class="headerlink" href="index.html#specifying-the-parser-to-use" title="Permalink to this headline">¶</a></h1>
<p>If you just need to parse some HTML, you can dump the markup into the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor, and it&#8217;ll probably be fine. Beautiful
Soup will pick a parser for you and parse the data. But there are a
few additional arguments you can pass in to the constructor to change
which parser is used.</p>
<p>The first argument to the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor is a string or
an open filehandle&#8211;the markup you want parsed. The second argument is
<cite>how</cite> you&#8217;d like the markup parsed.</p>
<p>If you don&#8217;t specify anything, you&#8217;ll get the best HTML parser that&#8217;s
installed. Beautiful Soup ranks lxml&#8217;s parser as being the best, then
html5lib&#8217;s, then Python&#8217;s built-in parser. You can override this by
specifying one of the following:</p>
<ul class="simple">
<li>What type of markup you want to parse. Currently supported are
&#8220;html&#8221;, &#8220;xml&#8221;, and &#8220;html5&#8221;.</li>
<li>The name of the parser library you want to use. Currently supported
options are &#8220;lxml&#8221;, &#8220;html5lib&#8221;, and &#8220;html.parser&#8221; (Python&#8217;s
built-in HTML parser).</li>
</ul>
<p>The section <a class="reference internal" href="index.html#installing-a-parser">Installing a parser</a> contrasts the supported parsers.</p>
<p>If you don&#8217;t have an appropriate parser installed, Beautiful Soup will
ignore your request and pick a different parser. Right now, the only
supported XML parser is lxml. If you don&#8217;t have lxml installed, asking
for an XML parser won&#8217;t give you one, and asking for &#8220;lxml&#8221; won&#8217;t work
either.</p>
<div class="section" id="differences-between-parsers">
<h2>Differences between parsers<a class="headerlink" href="index.html#differences-between-parsers" title="Permalink to this headline">¶</a></h2>
<p>Beautiful Soup presents the same interface to a number of different
parsers, but each parser is different. Different parsers will create
different parse trees from the same document. The biggest differences
are between the HTML parsers and the XML parsers. Here&#8217;s a short
document, parsed as HTML:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;b /&gt;&lt;/a&gt;&quot;</span><span class="p">)</span>
<span class="c"># &lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;a&gt;&lt;b&gt;&lt;/b&gt;&lt;/a&gt;&lt;/body&gt;&lt;/html&gt;</span>
</pre></div>
</div>
<p>Since an empty &lt;b /&gt; tag is not valid HTML, the parser turns it into a
&lt;b&gt;&lt;/b&gt; tag pair.</p>
<p>Here&#8217;s the same document parsed as XML (running this requires that you
have lxml installed). Note that the empty &lt;b /&gt; tag is left alone, and
that the document is given an XML declaration instead of being put
into an &lt;html&gt; tag.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;b /&gt;&lt;/a&gt;&quot;</span><span class="p">,</span> <span class="s">&quot;xml&quot;</span><span class="p">)</span>
<span class="c"># &lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;</span>
<span class="c"># &lt;a&gt;&lt;b/&gt;&lt;/a&gt;</span>
</pre></div>
</div>
<p>There are also differences between HTML parsers. If you give Beautiful
Soup a perfectly-formed HTML document, these differences won&#8217;t
matter. One parser will be faster than another, but they&#8217;ll all give
you a data structure that looks exactly like the original HTML
document.</p>
<p>But if the document is not perfectly-formed, different parsers will
give different results. Here&#8217;s a short, invalid document parsed using
lxml&#8217;s HTML parser. Note that the dangling &lt;/p&gt; tag is simply
ignored:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;/p&gt;&quot;</span><span class="p">,</span> <span class="s">&quot;lxml&quot;</span><span class="p">)</span>
<span class="c"># &lt;html&gt;&lt;body&gt;&lt;a&gt;&lt;/a&gt;&lt;/body&gt;&lt;/html&gt;</span>
</pre></div>
</div>
<p>Here&#8217;s the same document parsed using html5lib:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;/p&gt;&quot;</span><span class="p">,</span> <span class="s">&quot;html5lib&quot;</span><span class="p">)</span>
<span class="c"># &lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;a&gt;&lt;p&gt;&lt;/p&gt;&lt;/a&gt;&lt;/body&gt;&lt;/html&gt;</span>
</pre></div>
</div>
<p>Instead of ignoring the dangling &lt;/p&gt; tag, html5lib pairs it with an
opening &lt;p&gt; tag. This parser also adds an empty &lt;head&gt; tag to the
document.</p>
<p>Here&#8217;s the same document parsed with Python&#8217;s built-in HTML
parser:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">BeautifulSoup</span><span class="p">(</span><span class="s">&quot;&lt;a&gt;&lt;/p&gt;&quot;</span><span class="p">,</span> <span class="s">&quot;html.parser&quot;</span><span class="p">)</span>
<span class="c"># &lt;a&gt;&lt;/a&gt;</span>
</pre></div>
</div>
<p>Like html5lib, this parser ignores the closing &lt;/p&gt; tag. Unlike
html5lib, this parser makes no attempt to create a well-formed HTML
document by adding a &lt;body&gt; tag. Unlike lxml, it doesn&#8217;t even bother
to add an &lt;html&gt; tag.</p>
<p>Since the document &#8220;&lt;a&gt;&lt;/p&gt;&#8221; is invalid, none of these techniques is
the &#8220;correct&#8221; way to handle it. The html5lib parser uses techniques
that are part of the HTML5 standard, so it has the best claim on being
the &#8220;correct&#8221; way, but all three techniques are legitimate.</p>
<p>Differences between parsers can affect your script. If you&#8217;re planning
on distributing your script to other people, or running it on multiple
machines, you should specify a parser in the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt>
constructor. That will reduce the chances that your users parse a
document differently from the way you parse it.</p>
</div>
</div>
<div class="section" id="encodings">
<h1>Encodings<a class="headerlink" href="index.html#encodings" title="Permalink to this headline">¶</a></h1>
<p>Any HTML or XML document is written in a specific encoding like ASCII
or UTF-8.  But when you load that document into Beautiful Soup, you&#8217;ll
discover it&#8217;s been converted to Unicode:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">&quot;&lt;h1&gt;Sacr</span><span class="se">\xc3\xa9</span><span class="s"> bleu!&lt;/h1&gt;&quot;</span>
<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">h1</span>
<span class="c"># &lt;h1&gt;Sacré bleu!&lt;/h1&gt;</span>
<span class="n">soup</span><span class="o">.</span><span class="n">h1</span><span class="o">.</span><span class="n">string</span>
<span class="c"># u&#39;Sacr\xe9 bleu!&#39;</span>
</pre></div>
</div>
<p>It&#8217;s not magic. (That sure would be nice.) Beautiful Soup uses a
sub-library called <a class="reference internal" href="index.html#unicode-dammit">Unicode, Dammit</a> to detect a document&#8217;s encoding
and convert it to Unicode. The autodetected encoding is available as
the <tt class="docutils literal"><span class="pre">.original_encoding</span></tt> attribute of the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">original_encoding</span>
<span class="s">&#39;utf-8&#39;</span>
</pre></div>
</div>
<p>Unicode, Dammit guesses correctly most of the time, but sometimes it
makes mistakes. Sometimes it guesses correctly, but only after a
byte-by-byte search of the document that takes a very long time. If
you happen to know a document&#8217;s encoding ahead of time, you can avoid
mistakes and delays by passing it to the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor
as <tt class="docutils literal"><span class="pre">from_encoding</span></tt>.</p>
<p>Here&#8217;s a document written in ISO-8859-8. The document is so short that
Unicode, Dammit can&#8217;t get a good lock on it, and misidentifies it as
ISO-8859-7:</p>
<div class="highlight-python"><pre>markup = b"&lt;h1&gt;\xed\xe5\xec\xf9&lt;/h1&gt;"
soup = BeautifulSoup(markup)
soup.h1
&lt;h1&gt;νεμω&lt;/h1&gt;
soup.original_encoding
'ISO-8859-7'</pre>
</div>
<p>We can fix this by passing in the correct <tt class="docutils literal"><span class="pre">from_encoding</span></tt>:</p>
<div class="highlight-python"><pre>soup = BeautifulSoup(markup, from_encoding="iso-8859-8")
soup.h1
&lt;h1&gt;םולש&lt;/h1&gt;
soup.original_encoding
'iso8859-8'</pre>
</div>
<p>In rare cases (usually when a UTF-8 document contains text written in
a completely different encoding), the only way to get Unicode may be
to replace some characters with the special Unicode character
&#8220;REPLACEMENT CHARACTER&#8221; (U+FFFD, �). If Unicode, Dammit needs to do
this, it will set the <tt class="docutils literal"><span class="pre">.contains_replacement_characters</span></tt> attribute
to <tt class="docutils literal"><span class="pre">True</span></tt> on the <tt class="docutils literal"><span class="pre">UnicodeDammit</span></tt> or <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object. This
lets you know that the Unicode representation is not an exact
representation of the original&#8211;some data was lost. If a document
contains �, but <tt class="docutils literal"><span class="pre">.contains_replacement_characters</span></tt> is <tt class="docutils literal"><span class="pre">False</span></tt>,
you&#8217;ll know that the � was there originally (as it is in this
paragraph) and doesn&#8217;t stand in for missing data.</p>
<div class="section" id="output-encoding">
<h2>Output encoding<a class="headerlink" href="index.html#output-encoding" title="Permalink to this headline">¶</a></h2>
<p>When you write out a document from Beautiful Soup, you get a UTF-8
document, even if the document wasn&#8217;t in UTF-8 to begin with. Here&#8217;s a
document written in the Latin-1 encoding:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="n">b</span><span class="s">&#39;&#39;&#39;</span>
<span class="s"> &lt;html&gt;</span>
<span class="s">  &lt;head&gt;</span>
<span class="s">   &lt;meta content=&quot;text/html; charset=ISO-Latin-1&quot; http-equiv=&quot;Content-type&quot; /&gt;</span>
<span class="s">  &lt;/head&gt;</span>
<span class="s">  &lt;body&gt;</span>
<span class="s">   &lt;p&gt;Sacr</span><span class="se">\xe9</span><span class="s"> bleu!&lt;/p&gt;</span>
<span class="s">  &lt;/body&gt;</span>
<span class="s"> &lt;/html&gt;</span>
<span class="s">&#39;&#39;&#39;</span>

<span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;head&gt;</span>
<span class="c">#   &lt;meta content=&quot;text/html; charset=utf-8&quot; http-equiv=&quot;Content-type&quot; /&gt;</span>
<span class="c">#  &lt;/head&gt;</span>
<span class="c">#  &lt;body&gt;</span>
<span class="c">#   &lt;p&gt;</span>
<span class="c">#    Sacré bleu!</span>
<span class="c">#   &lt;/p&gt;</span>
<span class="c">#  &lt;/body&gt;</span>
<span class="c"># &lt;/html&gt;</span>
</pre></div>
</div>
<p>Note that the &lt;meta&gt; tag has been rewritten to reflect the fact that
the document is now in UTF-8.</p>
<p>If you don&#8217;t want UTF-8, you can pass an encoding into <tt class="docutils literal"><span class="pre">prettify()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">soup</span><span class="o">.</span><span class="n">prettify</span><span class="p">(</span><span class="s">&quot;latin-1&quot;</span><span class="p">))</span>
<span class="c"># &lt;html&gt;</span>
<span class="c">#  &lt;head&gt;</span>
<span class="c">#   &lt;meta content=&quot;text/html; charset=latin-1&quot; http-equiv=&quot;Content-type&quot; /&gt;</span>
<span class="c"># ...</span>
</pre></div>
</div>
<p>You can also call encode() on the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> object, or any
element in the soup, just as if it were a Python string:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span><span class="o">.</span><span class="n">p</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;latin-1&quot;</span><span class="p">)</span>
<span class="c"># &#39;&lt;p&gt;Sacr\xe9 bleu!&lt;/p&gt;&#39;</span>

<span class="n">soup</span><span class="o">.</span><span class="n">p</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;utf-8&quot;</span><span class="p">)</span>
<span class="c"># &#39;&lt;p&gt;Sacr\xc3\xa9 bleu!&lt;/p&gt;&#39;</span>
</pre></div>
</div>
<p>Any characters that can&#8217;t be represented in your chosen encoding will
be converted into numeric XML entity references. Here&#8217;s a document
that includes the Unicode character SNOWMAN:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="s">u&quot;&lt;b&gt;</span><span class="se">\N{SNOWMAN}</span><span class="s">&lt;/b&gt;&quot;</span>
<span class="n">snowman_soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">)</span>
<span class="n">tag</span> <span class="o">=</span> <span class="n">snowman_soup</span><span class="o">.</span><span class="n">b</span>
</pre></div>
</div>
<p>The SNOWMAN character can be part of a UTF-8 document (it looks like
☃), but there&#8217;s no representation for that character in ISO-Latin-1 or
ASCII, so it&#8217;s converted into &#8220;&amp;#9731&#8221; for those encodings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">tag</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;utf-8&quot;</span><span class="p">))</span>
<span class="c"># &lt;b&gt;☃&lt;/b&gt;</span>

<span class="k">print</span> <span class="n">tag</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;latin-1&quot;</span><span class="p">)</span>
<span class="c"># &lt;b&gt;&amp;#9731;&lt;/b&gt;</span>

<span class="k">print</span> <span class="n">tag</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;ascii&quot;</span><span class="p">)</span>
<span class="c"># &lt;b&gt;&amp;#9731;&lt;/b&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="unicode-dammit">
<h2>Unicode, Dammit<a class="headerlink" href="index.html#unicode-dammit" title="Permalink to this headline">¶</a></h2>
<p>You can use Unicode, Dammit without using Beautiful Soup. It&#8217;s useful
whenever you have data in an unknown encoding and you just want it to
become Unicode:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">UnicodeDammit</span>
<span class="n">dammit</span> <span class="o">=</span> <span class="n">UnicodeDammit</span><span class="p">(</span><span class="s">&quot;Sacr</span><span class="se">\xc3\xa9</span><span class="s"> bleu!&quot;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">dammit</span><span class="o">.</span><span class="n">unicode_markup</span><span class="p">)</span>
<span class="c"># Sacré bleu!</span>
<span class="n">dammit</span><span class="o">.</span><span class="n">original_encoding</span>
<span class="c"># &#39;utf-8&#39;</span>
</pre></div>
</div>
<p>Unicode, Dammit&#8217;s guesses will get a lot more accurate if you install
the <tt class="docutils literal"><span class="pre">chardet</span></tt> or <tt class="docutils literal"><span class="pre">cchardet</span></tt> Python libraries. The more data you
give Unicode, Dammit, the more accurately it will guess. If you have
your own suspicions as to what the encoding might be, you can pass
them in as a list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">dammit</span> <span class="o">=</span> <span class="n">UnicodeDammit</span><span class="p">(</span><span class="s">&quot;Sacr</span><span class="se">\xe9</span><span class="s"> bleu!&quot;</span><span class="p">,</span> <span class="p">[</span><span class="s">&quot;latin-1&quot;</span><span class="p">,</span> <span class="s">&quot;iso-8859-1&quot;</span><span class="p">])</span>
<span class="k">print</span><span class="p">(</span><span class="n">dammit</span><span class="o">.</span><span class="n">unicode_markup</span><span class="p">)</span>
<span class="c"># Sacré bleu!</span>
<span class="n">dammit</span><span class="o">.</span><span class="n">original_encoding</span>
<span class="c"># &#39;latin-1&#39;</span>
</pre></div>
</div>
<p>Unicode, Dammit has two special features that Beautiful Soup doesn&#8217;t
use.</p>
<div class="section" id="smart-quotes">
<h3>Smart quotes<a class="headerlink" href="index.html#smart-quotes" title="Permalink to this headline">¶</a></h3>
<p>You can use Unicode, Dammit to convert Microsoft smart quotes to HTML or XML
entities:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">markup</span> <span class="o">=</span> <span class="n">b</span><span class="s">&quot;&lt;p&gt;I just </span><span class="se">\x93</span><span class="s">love</span><span class="se">\x94</span><span class="s"> Microsoft Word</span><span class="se">\x92</span><span class="s">s smart quotes&lt;/p&gt;&quot;</span>

<span class="n">UnicodeDammit</span><span class="p">(</span><span class="n">markup</span><span class="p">,</span> <span class="p">[</span><span class="s">&quot;windows-1252&quot;</span><span class="p">],</span> <span class="n">smart_quotes_to</span><span class="o">=</span><span class="s">&quot;html&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">unicode_markup</span>
<span class="c"># u&#39;&lt;p&gt;I just &amp;ldquo;love&amp;rdquo; Microsoft Word&amp;rsquo;s smart quotes&lt;/p&gt;&#39;</span>

<span class="n">UnicodeDammit</span><span class="p">(</span><span class="n">markup</span><span class="p">,</span> <span class="p">[</span><span class="s">&quot;windows-1252&quot;</span><span class="p">],</span> <span class="n">smart_quotes_to</span><span class="o">=</span><span class="s">&quot;xml&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">unicode_markup</span>
<span class="c"># u&#39;&lt;p&gt;I just &amp;#x201C;love&amp;#x201D; Microsoft Word&amp;#x2019;s smart quotes&lt;/p&gt;&#39;</span>
</pre></div>
</div>
<p>You can also convert Microsoft smart quotes to ASCII quotes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">UnicodeDammit</span><span class="p">(</span><span class="n">markup</span><span class="p">,</span> <span class="p">[</span><span class="s">&quot;windows-1252&quot;</span><span class="p">],</span> <span class="n">smart_quotes_to</span><span class="o">=</span><span class="s">&quot;ascii&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">unicode_markup</span>
<span class="c"># u&#39;&lt;p&gt;I just &quot;love&quot; Microsoft Word\&#39;s smart quotes&lt;/p&gt;&#39;</span>
</pre></div>
</div>
<p>Hopefully you&#8217;ll find this feature useful, but Beautiful Soup doesn&#8217;t
use it. Beautiful Soup prefers the default behavior, which is to
convert Microsoft smart quotes to Unicode characters along with
everything else:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">UnicodeDammit</span><span class="p">(</span><span class="n">markup</span><span class="p">,</span> <span class="p">[</span><span class="s">&quot;windows-1252&quot;</span><span class="p">])</span><span class="o">.</span><span class="n">unicode_markup</span>
<span class="c"># u&#39;&lt;p&gt;I just \u201clove\u201d Microsoft Word\u2019s smart quotes&lt;/p&gt;&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="inconsistent-encodings">
<h3>Inconsistent encodings<a class="headerlink" href="index.html#inconsistent-encodings" title="Permalink to this headline">¶</a></h3>
<p>Sometimes a document is mostly in UTF-8, but contains Windows-1252
characters such as (again) Microsoft smart quotes. This can happen
when a website includes data from multiple sources. You can use
<tt class="docutils literal"><span class="pre">UnicodeDammit.detwingle()</span></tt> to turn such a document into pure
UTF-8. Here&#8217;s a simple example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">snowmen</span> <span class="o">=</span> <span class="p">(</span><span class="s">u&quot;</span><span class="se">\N{SNOWMAN}</span><span class="s">&quot;</span> <span class="o">*</span> <span class="mi">3</span><span class="p">)</span>
<span class="n">quote</span> <span class="o">=</span> <span class="p">(</span><span class="s">u&quot;</span><span class="se">\N{LEFT DOUBLE QUOTATION MARK}</span><span class="s">I like snowmen!</span><span class="se">\N{RIGHT DOUBLE QUOTATION MARK}</span><span class="s">&quot;</span><span class="p">)</span>
<span class="n">doc</span> <span class="o">=</span> <span class="n">snowmen</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;utf8&quot;</span><span class="p">)</span> <span class="o">+</span> <span class="n">quote</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&quot;windows_1252&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>This document is a mess. The snowmen are in UTF-8 and the quotes are
in Windows-1252. You can display the snowmen or the quotes, but not
both:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
<span class="c"># ☃☃☃�I like snowmen!�</span>

<span class="k">print</span><span class="p">(</span><span class="n">doc</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&quot;windows-1252&quot;</span><span class="p">))</span>
<span class="c"># â˜ƒâ˜ƒâ˜ƒ“I like snowmen!”</span>
</pre></div>
</div>
<p>Decoding the document as UTF-8 raises a <tt class="docutils literal"><span class="pre">UnicodeDecodeError</span></tt>, and
decoding it as Windows-1252 gives you gibberish. Fortunately,
<tt class="docutils literal"><span class="pre">UnicodeDammit.detwingle()</span></tt> will convert the string to pure UTF-8,
allowing you to decode it to Unicode and display the snowmen and quote
marks simultaneously:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">new_doc</span> <span class="o">=</span> <span class="n">UnicodeDammit</span><span class="o">.</span><span class="n">detwingle</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">new_doc</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&quot;utf8&quot;</span><span class="p">))</span>
<span class="c"># ☃☃☃“I like snowmen!”</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">UnicodeDammit.detwingle()</span></tt> only knows how to handle Windows-1252
embedded in UTF-8 (or vice versa, I suppose), but this is the most
common case.</p>
<p>Note that you must know to call <tt class="docutils literal"><span class="pre">UnicodeDammit.detwingle()</span></tt> on your
data before passing it into <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> or the <tt class="docutils literal"><span class="pre">UnicodeDammit</span></tt>
constructor. Beautiful Soup assumes that a document has a single
encoding, whatever it might be. If you pass it a document that
contains both UTF-8 and Windows-1252, it&#8217;s likely to think the whole
document is Windows-1252, and the document will come out looking like
` â˜ƒâ˜ƒâ˜ƒ“I like snowmen!”<a href="index.html#id14"><span class="problematic" id="id15">`</span></a>.</p>
<p><tt class="docutils literal"><span class="pre">UnicodeDammit.detwingle()</span></tt> is new in Beautiful Soup 4.1.0.</p>
</div>
</div>
</div>
<div class="section" id="parsing-only-part-of-a-document">
<h1>Parsing only part of a document<a class="headerlink" href="index.html#parsing-only-part-of-a-document" title="Permalink to this headline">¶</a></h1>
<p>Let&#8217;s say you want to use Beautiful Soup look at a document&#8217;s &lt;a&gt;
tags. It&#8217;s a waste of time and memory to parse the entire document and
then go over it again looking for &lt;a&gt; tags. It would be much faster to
ignore everything that wasn&#8217;t an &lt;a&gt; tag in the first place. The
<tt class="docutils literal"><span class="pre">SoupStrainer</span></tt> class allows you to choose which parts of an incoming
document are parsed. You just create a <tt class="docutils literal"><span class="pre">SoupStrainer</span></tt> and pass it in
to the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor as the <tt class="docutils literal"><span class="pre">parse_only</span></tt> argument.</p>
<p>(Note that <em>this feature won&#8217;t work if you&#8217;re using the html5lib parser</em>.
If you use html5lib, the whole document will be parsed, no
matter what. This is because html5lib constantly rearranges the parse
tree as it works, and if some part of the document didn&#8217;t actually
make it into the parse tree, it&#8217;ll crash. To avoid confusion, in the
examples below I&#8217;ll be forcing Beautiful Soup to use Python&#8217;s
built-in parser.)</p>
<div class="section" id="soupstrainer">
<h2><tt class="docutils literal"><span class="pre">SoupStrainer</span></tt><a class="headerlink" href="index.html#soupstrainer" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">SoupStrainer</span></tt> class takes the same arguments as a typical
method from <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>: <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#attrs"><em>attrs</em></a>, <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>, and <a class="reference internal" href="index.html#kwargs"><em>**kwargs</em></a>. Here are
three <tt class="docutils literal"><span class="pre">SoupStrainer</span></tt> objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">SoupStrainer</span>

<span class="n">only_a_tags</span> <span class="o">=</span> <span class="n">SoupStrainer</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>

<span class="n">only_tags_with_id_link2</span> <span class="o">=</span> <span class="n">SoupStrainer</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="s">&quot;link2&quot;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">is_short_string</span><span class="p">(</span><span class="n">string</span><span class="p">):</span>
    <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="n">string</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">10</span>

<span class="n">only_short_strings</span> <span class="o">=</span> <span class="n">SoupStrainer</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">is_short_string</span><span class="p">)</span>
</pre></div>
</div>
<p>I&#8217;m going to bring back the &#8220;three sisters&#8221; document one more time,
and we&#8217;ll see what the document looks like when it&#8217;s parsed with these
three <tt class="docutils literal"><span class="pre">SoupStrainer</span></tt> objects:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">html_doc</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span>
<span class="s">&lt;html&gt;&lt;head&gt;&lt;title&gt;The Dormouse&#39;s story&lt;/title&gt;&lt;/head&gt;</span>

<span class="s">&lt;p class=&quot;title&quot;&gt;&lt;b&gt;The Dormouse&#39;s story&lt;/b&gt;&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;Once upon a time there were three little sisters; and their names were</span>
<span class="s">&lt;a href=&quot;http://example.com/elsie&quot; class=&quot;sister&quot; id=&quot;link1&quot;&gt;Elsie&lt;/a&gt;,</span>
<span class="s">&lt;a href=&quot;http://example.com/lacie&quot; class=&quot;sister&quot; id=&quot;link2&quot;&gt;Lacie&lt;/a&gt; and</span>
<span class="s">&lt;a href=&quot;http://example.com/tillie&quot; class=&quot;sister&quot; id=&quot;link3&quot;&gt;Tillie&lt;/a&gt;;</span>
<span class="s">and they lived at the bottom of a well.&lt;/p&gt;</span>

<span class="s">&lt;p class=&quot;story&quot;&gt;...&lt;/p&gt;</span>
<span class="s">&quot;&quot;&quot;</span>

<span class="k">print</span><span class="p">(</span><span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">,</span> <span class="s">&quot;html.parser&quot;</span><span class="p">,</span> <span class="n">parse_only</span><span class="o">=</span><span class="n">only_a_tags</span><span class="p">)</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/elsie&quot; id=&quot;link1&quot;&gt;</span>
<span class="c">#  Elsie</span>
<span class="c"># &lt;/a&gt;</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;</span>
<span class="c">#  Lacie</span>
<span class="c"># &lt;/a&gt;</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/tillie&quot; id=&quot;link3&quot;&gt;</span>
<span class="c">#  Tillie</span>
<span class="c"># &lt;/a&gt;</span>

<span class="k">print</span><span class="p">(</span><span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">,</span> <span class="s">&quot;html.parser&quot;</span><span class="p">,</span> <span class="n">parse_only</span><span class="o">=</span><span class="n">only_tags_with_id_link2</span><span class="p">)</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># &lt;a class=&quot;sister&quot; href=&quot;http://example.com/lacie&quot; id=&quot;link2&quot;&gt;</span>
<span class="c">#  Lacie</span>
<span class="c"># &lt;/a&gt;</span>

<span class="k">print</span><span class="p">(</span><span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">,</span> <span class="s">&quot;html.parser&quot;</span><span class="p">,</span> <span class="n">parse_only</span><span class="o">=</span><span class="n">only_short_strings</span><span class="p">)</span><span class="o">.</span><span class="n">prettify</span><span class="p">())</span>
<span class="c"># Elsie</span>
<span class="c"># ,</span>
<span class="c"># Lacie</span>
<span class="c"># and</span>
<span class="c"># Tillie</span>
<span class="c"># ...</span>
<span class="c">#</span>
</pre></div>
</div>
<p>You can also pass a <tt class="docutils literal"><span class="pre">SoupStrainer</span></tt> into any of the methods covered
in <a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a>. This probably isn&#8217;t terribly useful, but I
thought I&#8217;d mention it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">html_doc</span><span class="p">)</span>
<span class="n">soup</span><span class="o">.</span><span class="n">find_all</span><span class="p">(</span><span class="n">only_short_strings</span><span class="p">)</span>
<span class="c"># [u&#39;\n\n&#39;, u&#39;\n\n&#39;, u&#39;Elsie&#39;, u&#39;,\n&#39;, u&#39;Lacie&#39;, u&#39; and\n&#39;, u&#39;Tillie&#39;,</span>
<span class="c">#  u&#39;\n\n&#39;, u&#39;...&#39;, u&#39;\n&#39;]</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="troubleshooting">
<h1>Troubleshooting<a class="headerlink" href="index.html#troubleshooting" title="Permalink to this headline">¶</a></h1>
<div class="section" id="diagnose">
<span id="id16"></span><h2><tt class="docutils literal"><span class="pre">diagnose()</span></tt><a class="headerlink" href="index.html#diagnose" title="Permalink to this headline">¶</a></h2>
<p>If you&#8217;re having trouble understanding what Beautiful Soup does to a
document, pass the document into the <tt class="docutils literal"><span class="pre">diagnose()</span></tt> function. (New in
Beautiful Soup 4.2.0.)  Beautiful Soup will print out a report showing
you how different parsers handle the document, and tell you if you&#8217;re
missing a parser that Beautiful Soup could be using:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4.diagnose</span> <span class="kn">import</span> <span class="n">diagnose</span>
<span class="n">data</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s">&quot;bad.html&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="n">diagnose</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>

<span class="c"># Diagnostic running on Beautiful Soup 4.2.0</span>
<span class="c"># Python version 2.7.3 (default, Aug  1 2012, 05:16:07)</span>
<span class="c"># I noticed that html5lib is not installed. Installing it may help.</span>
<span class="c"># Found lxml version 2.3.2.0</span>
<span class="c">#</span>
<span class="c"># Trying to parse your data with html.parser</span>
<span class="c"># Here&#39;s what html.parser did with the document:</span>
<span class="c"># ...</span>
</pre></div>
</div>
<p>Just looking at the output of diagnose() may show you how to solve the
problem. Even if not, you can paste the output of <tt class="docutils literal"><span class="pre">diagnose()</span></tt> when
asking for help.</p>
</div>
<div class="section" id="errors-when-parsing-a-document">
<h2>Errors when parsing a document<a class="headerlink" href="index.html#errors-when-parsing-a-document" title="Permalink to this headline">¶</a></h2>
<p>There are two different kinds of parse errors. There are crashes,
where you feed a document to Beautiful Soup and it raises an
exception, usually an <tt class="docutils literal"><span class="pre">HTMLParser.HTMLParseError</span></tt>. And there is
unexpected behavior, where a Beautiful Soup parse tree looks a lot
different than the document used to create it.</p>
<p>Almost none of these problems turn out to be problems with Beautiful
Soup. This is not because Beautiful Soup is an amazingly well-written
piece of software. It&#8217;s because Beautiful Soup doesn&#8217;t include any
parsing code. Instead, it relies on external parsers. If one parser
isn&#8217;t working on a certain document, the best solution is to try a
different parser. See <a class="reference internal" href="index.html#installing-a-parser">Installing a parser</a> for details and a parser
comparison.</p>
<p>The most common parse errors are <tt class="docutils literal"><span class="pre">HTMLParser.HTMLParseError:</span>
<span class="pre">malformed</span> <span class="pre">start</span> <span class="pre">tag</span></tt> and <tt class="docutils literal"><span class="pre">HTMLParser.HTMLParseError:</span> <span class="pre">bad</span> <span class="pre">end</span>
<span class="pre">tag</span></tt>. These are both generated by Python&#8217;s built-in HTML parser
library, and the solution is to <a class="reference internal" href="index.html#parser-installation"><em>install lxml or
html5lib.</em></a></p>
<p>The most common type of unexpected behavior is that you can&#8217;t find a
tag that you know is in the document. You saw it going in, but
<tt class="docutils literal"><span class="pre">find_all()</span></tt> returns <tt class="docutils literal"><span class="pre">[]</span></tt> or <tt class="docutils literal"><span class="pre">find()</span></tt> returns <tt class="docutils literal"><span class="pre">None</span></tt>. This is
another common problem with Python&#8217;s built-in HTML parser, which
sometimes skips tags it doesn&#8217;t understand.  Again, the solution is to
<a class="reference internal" href="index.html#parser-installation"><em>install lxml or html5lib.</em></a></p>
</div>
<div class="section" id="version-mismatch-problems">
<h2>Version mismatch problems<a class="headerlink" href="index.html#version-mismatch-problems" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">SyntaxError:</span> <span class="pre">Invalid</span> <span class="pre">syntax</span></tt> (on the line <tt class="docutils literal"><span class="pre">ROOT_TAG_NAME</span> <span class="pre">=</span>
<span class="pre">u'[document]'</span></tt>): Caused by running the Python 2 version of
Beautiful Soup under Python 3, without converting the code.</li>
<li><tt class="docutils literal"><span class="pre">ImportError:</span> <span class="pre">No</span> <span class="pre">module</span> <span class="pre">named</span> <span class="pre">HTMLParser</span></tt> - Caused by running the
Python 2 version of Beautiful Soup under Python 3.</li>
<li><tt class="docutils literal"><span class="pre">ImportError:</span> <span class="pre">No</span> <span class="pre">module</span> <span class="pre">named</span> <span class="pre">html.parser</span></tt> - Caused by running the
Python 3 version of Beautiful Soup under Python 2.</li>
<li><tt class="docutils literal"><span class="pre">ImportError:</span> <span class="pre">No</span> <span class="pre">module</span> <span class="pre">named</span> <span class="pre">BeautifulSoup</span></tt> - Caused by running
Beautiful Soup 3 code on a system that doesn&#8217;t have BS3
installed. Or, by writing Beautiful Soup 4 code without knowing that
the package name has changed to <tt class="docutils literal"><span class="pre">bs4</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">ImportError:</span> <span class="pre">No</span> <span class="pre">module</span> <span class="pre">named</span> <span class="pre">bs4</span></tt> - Caused by running Beautiful
Soup 4 code on a system that doesn&#8217;t have BS4 installed.</li>
</ul>
</div>
<div class="section" id="parsing-xml">
<span id="id17"></span><h2>Parsing XML<a class="headerlink" href="index.html#parsing-xml" title="Permalink to this headline">¶</a></h2>
<p>By default, Beautiful Soup parses documents as HTML. To parse a
document as XML, pass in &#8220;xml&#8221; as the second argument to the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">soup</span> <span class="o">=</span> <span class="n">BeautifulSoup</span><span class="p">(</span><span class="n">markup</span><span class="p">,</span> <span class="s">&quot;xml&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>You&#8217;ll need to <a class="reference internal" href="index.html#parser-installation"><em>have lxml installed</em></a>.</p>
</div>
<div class="section" id="other-parser-problems">
<h2>Other parser problems<a class="headerlink" href="index.html#other-parser-problems" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>If your script works on one computer but not another, it&#8217;s probably
because the two computers have different parser libraries
available. For example, you may have developed the script on a
computer that has lxml installed, and then tried to run it on a
computer that only has html5lib installed. See <a class="reference internal" href="index.html#differences-between-parsers">Differences between
parsers</a> for why this matters, and fix the problem by mentioning a
specific parser library in the <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor.</li>
<li>Because <a class="reference external" href="http://www.w3.org/TR/html5/syntax.html#syntax">HTML tags and attributes are case-insensitive</a>, all three HTML
parsers convert tag and attribute names to lowercase. That is, the
markup &lt;TAG&gt;&lt;/TAG&gt; is converted to &lt;tag&gt;&lt;/tag&gt;. If you want to
preserve mixed-case or uppercase tags and attributes, you&#8217;ll need to
<a class="reference internal" href="index.html#parsing-xml"><em>parse the document as XML.</em></a></li>
</ul>
</div>
<div class="section" id="miscellaneous">
<span id="misc"></span><h2>Miscellaneous<a class="headerlink" href="index.html#miscellaneous" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">UnicodeEncodeError:</span> <span class="pre">'charmap'</span> <span class="pre">codec</span> <span class="pre">can't</span> <span class="pre">encode</span> <span class="pre">character</span>
<span class="pre">u'\xfoo'</span> <span class="pre">in</span> <span class="pre">position</span> <span class="pre">bar</span></tt> (or just about any other
<tt class="docutils literal"><span class="pre">UnicodeEncodeError</span></tt>) - This is not a problem with Beautiful Soup.
This problem shows up in two main situations. First, when you try to
print a Unicode character that your console doesn&#8217;t know how to
display. (See <a class="reference external" href="http://wiki.python.org/moin/PrintFails">this page on the Python wiki</a> for help.) Second, when
you&#8217;re writing to a file and you pass in a Unicode character that&#8217;s
not supported by your default encoding.  In this case, the simplest
solution is to explicitly encode the Unicode string into UTF-8 with
<tt class="docutils literal"><span class="pre">u.encode(&quot;utf8&quot;)</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">KeyError:</span> <span class="pre">[attr]</span></tt> - Caused by accessing <tt class="docutils literal"><span class="pre">tag['attr']</span></tt> when the
tag in question doesn&#8217;t define the <tt class="docutils literal"><span class="pre">attr</span></tt> attribute. The most
common errors are <tt class="docutils literal"><span class="pre">KeyError:</span> <span class="pre">'href'</span></tt> and <tt class="docutils literal"><span class="pre">KeyError:</span>
<span class="pre">'class'</span></tt>. Use <tt class="docutils literal"><span class="pre">tag.get('attr')</span></tt> if you&#8217;re not sure <tt class="docutils literal"><span class="pre">attr</span></tt> is
defined, just as you would with a Python dictionary.</li>
<li><tt class="docutils literal"><span class="pre">AttributeError:</span> <span class="pre">'ResultSet'</span> <span class="pre">object</span> <span class="pre">has</span> <span class="pre">no</span> <span class="pre">attribute</span> <span class="pre">'foo'</span></tt> - This
usually happens because you expected <tt class="docutils literal"><span class="pre">find_all()</span></tt> to return a
single tag or string. But <tt class="docutils literal"><span class="pre">find_all()</span></tt> returns a _list_ of tags
and strings&#8211;a <tt class="docutils literal"><span class="pre">ResultSet</span></tt> object. You need to iterate over the
list and look at the <tt class="docutils literal"><span class="pre">.foo</span></tt> of each one. Or, if you really only
want one result, you need to use <tt class="docutils literal"><span class="pre">find()</span></tt> instead of
<tt class="docutils literal"><span class="pre">find_all()</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">AttributeError:</span> <span class="pre">'NoneType'</span> <span class="pre">object</span> <span class="pre">has</span> <span class="pre">no</span> <span class="pre">attribute</span> <span class="pre">'foo'</span></tt> - This
usually happens because you called <tt class="docutils literal"><span class="pre">find()</span></tt> and then tried to
access the <cite>.foo`</cite> attribute of the result. But in your case,
<tt class="docutils literal"><span class="pre">find()</span></tt> didn&#8217;t find anything, so it returned <tt class="docutils literal"><span class="pre">None</span></tt>, instead of
returning a tag or a string. You need to figure out why your
<tt class="docutils literal"><span class="pre">find()</span></tt> call isn&#8217;t returning anything.</li>
</ul>
</div>
<div class="section" id="improving-performance">
<h2>Improving Performance<a class="headerlink" href="index.html#improving-performance" title="Permalink to this headline">¶</a></h2>
<p>Beautiful Soup will never be as fast as the parsers it sits on top
of. If response time is critical, if you&#8217;re paying for computer time
by the hour, or if there&#8217;s any other reason why computer time is more
valuable than programmer time, you should forget about Beautiful Soup
and work directly atop <a class="reference external" href="http://lxml.de/">lxml</a>.</p>
<p>That said, there are things you can do to speed up Beautiful Soup. If
you&#8217;re not using lxml as the underlying parser, my advice is to
<a class="reference internal" href="index.html#parser-installation"><em>start</em></a>. Beautiful Soup parses documents
significantly faster using lxml than using html.parser or html5lib.</p>
<p>You can speed up encoding detection significantly by installing the
<a class="reference external" href="http://pypi.python.org/pypi/cchardet/">cchardet</a> library.</p>
<p><a class="reference internal" href="index.html#parsing-only-part-of-a-document">Parsing only part of a document</a> won&#8217;t save you much time parsing
the document, but it can save a lot of memory, and it&#8217;ll make
<cite>searching</cite> the document much faster.</p>
</div>
</div>
<div class="section" id="id18">
<h1>Beautiful Soup 3<a class="headerlink" href="index.html#id18" title="Permalink to this headline">¶</a></h1>
<p>Beautiful Soup 3 is the previous release series, and is no longer
being actively developed. It&#8217;s currently packaged with all major Linux
distributions:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">python-beautifulsoup</span></tt></p>
<p>It&#8217;s also published through PyPi as <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt>.:</p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">easy_install</span> <span class="pre">BeautifulSoup</span></tt></p>
<p><tt class="kbd docutils literal"><span class="pre">$</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">BeautifulSoup</span></tt></p>
<p>You can also <a class="reference external" href="http://www.crummy.com/software/BeautifulSoup/bs3/download/3.x/BeautifulSoup-3.2.0.tar.gz">download a tarball of Beautiful Soup 3.2.0</a>.</p>
<p>If you ran <tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">beautifulsoup</span></tt> or <tt class="docutils literal"><span class="pre">easy_install</span>
<span class="pre">BeautifulSoup</span></tt>, but your code doesn&#8217;t work, you installed Beautiful
Soup 3 by mistake. You need to run <tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">beautifulsoup4</span></tt>.</p>
<p><a class="reference external" href="http://www.crummy.com/software/BeautifulSoup/bs3/documentation.html">The documentation for Beautiful Soup 3 is archived online</a>.</p>
<div class="section" id="porting-code-to-bs4">
<h2>Porting code to BS4<a class="headerlink" href="index.html#porting-code-to-bs4" title="Permalink to this headline">¶</a></h2>
<p>Most code written against Beautiful Soup 3 will work against Beautiful
Soup 4 with one simple change. All you should have to do is change the
package name from <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> to <tt class="docutils literal"><span class="pre">bs4</span></tt>. So this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">BeautifulSoup</span> <span class="kn">import</span> <span class="n">BeautifulSoup</span>
</pre></div>
</div>
<p>becomes this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">bs4</span> <span class="kn">import</span> <span class="n">BeautifulSoup</span>
</pre></div>
</div>
<ul class="simple">
<li>If you get the <tt class="docutils literal"><span class="pre">ImportError</span></tt> &#8220;No module named BeautifulSoup&#8221;, your
problem is that you&#8217;re trying to run Beautiful Soup 3 code, but you
only have Beautiful Soup 4 installed.</li>
<li>If you get the <tt class="docutils literal"><span class="pre">ImportError</span></tt> &#8220;No module named bs4&#8221;, your problem
is that you&#8217;re trying to run Beautiful Soup 4 code, but you only
have Beautiful Soup 3 installed.</li>
</ul>
<p>Although BS4 is mostly backwards-compatible with BS3, most of its
methods have been deprecated and given new names for <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP 8 compliance</a>. There are numerous other
renames and changes, and a few of them break backwards compatibility.</p>
<p>Here&#8217;s what you&#8217;ll need to know to convert your BS3 code and habits to BS4:</p>
<div class="section" id="you-need-a-parser">
<h3>You need a parser<a class="headerlink" href="index.html#you-need-a-parser" title="Permalink to this headline">¶</a></h3>
<p>Beautiful Soup 3 used Python&#8217;s <tt class="docutils literal"><span class="pre">SGMLParser</span></tt>, a module that was
deprecated and removed in Python 3.0. Beautiful Soup 4 uses
<tt class="docutils literal"><span class="pre">html.parser</span></tt> by default, but you can plug in lxml or html5lib and
use that instead. See <a class="reference internal" href="index.html#installing-a-parser">Installing a parser</a> for a comparison.</p>
<p>Since <tt class="docutils literal"><span class="pre">html.parser</span></tt> is not the same parser as <tt class="docutils literal"><span class="pre">SGMLParser</span></tt>, it
will treat invalid markup differently. Usually the &#8220;difference&#8221; is
that <tt class="docutils literal"><span class="pre">html.parser</span></tt> crashes. In that case, you&#8217;ll need to install
another parser. But sometimes <tt class="docutils literal"><span class="pre">html.parser</span></tt> just creates a different
parse tree than <tt class="docutils literal"><span class="pre">SGMLParser</span></tt> would. If this happens, you may need to
update your BS3 scraping code to deal with the new tree.</p>
</div>
<div class="section" id="method-names">
<h3>Method names<a class="headerlink" href="index.html#method-names" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">renderContents</span></tt> -&gt; <tt class="docutils literal"><span class="pre">encode_contents</span></tt></li>
<li><tt class="docutils literal"><span class="pre">replaceWith</span></tt> -&gt; <tt class="docutils literal"><span class="pre">replace_with</span></tt></li>
<li><tt class="docutils literal"><span class="pre">replaceWithChildren</span></tt> -&gt; <tt class="docutils literal"><span class="pre">unwrap</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findAll</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_all</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findAllNext</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_all_next</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findAllPrevious</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_all_previous</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findNext</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_next</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findNextSibling</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_next_sibling</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findNextSiblings</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_next_siblings</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findParent</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_parent</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findParents</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_parents</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findPrevious</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_previous</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findPreviousSibling</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_previous_sibling</span></tt></li>
<li><tt class="docutils literal"><span class="pre">findPreviousSiblings</span></tt> -&gt; <tt class="docutils literal"><span class="pre">find_previous_siblings</span></tt></li>
<li><tt class="docutils literal"><span class="pre">nextSibling</span></tt> -&gt; <tt class="docutils literal"><span class="pre">next_sibling</span></tt></li>
<li><tt class="docutils literal"><span class="pre">previousSibling</span></tt> -&gt; <tt class="docutils literal"><span class="pre">previous_sibling</span></tt></li>
</ul>
<p>Some arguments to the Beautiful Soup constructor were renamed for the
same reasons:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">BeautifulSoup(parseOnlyThese=...)</span></tt> -&gt; <tt class="docutils literal"><span class="pre">BeautifulSoup(parse_only=...)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BeautifulSoup(fromEncoding=...)</span></tt> -&gt; <tt class="docutils literal"><span class="pre">BeautifulSoup(from_encoding=...)</span></tt></li>
</ul>
<p>I renamed one method for compatibility with Python 3:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Tag.has_key()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Tag.has_attr()</span></tt></li>
</ul>
<p>I renamed one attribute to use more accurate terminology:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">Tag.isSelfClosing</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Tag.is_empty_element</span></tt></li>
</ul>
<p>I renamed three attributes to avoid using words that have special
meaning to Python. Unlike the others, these changes are <em>not backwards
compatible.</em> If you used these attributes in BS3, your code will break
on BS4 until you change them.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">UnicodeDammit.unicode</span></tt> -&gt; <tt class="docutils literal"><span class="pre">UnicodeDammit.unicode_markup</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Tag.next</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Tag.next_element</span></tt></li>
<li><tt class="docutils literal"><span class="pre">Tag.previous</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Tag.previous_element</span></tt></li>
</ul>
</div>
<div class="section" id="generators">
<h3>Generators<a class="headerlink" href="index.html#generators" title="Permalink to this headline">¶</a></h3>
<p>I gave the generators PEP 8-compliant names, and transformed them into
properties:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">childGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">children</span></tt></li>
<li><tt class="docutils literal"><span class="pre">nextGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">next_elements</span></tt></li>
<li><tt class="docutils literal"><span class="pre">nextSiblingGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">next_siblings</span></tt></li>
<li><tt class="docutils literal"><span class="pre">previousGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">previous_elements</span></tt></li>
<li><tt class="docutils literal"><span class="pre">previousSiblingGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">previous_siblings</span></tt></li>
<li><tt class="docutils literal"><span class="pre">recursiveChildGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">descendants</span></tt></li>
<li><tt class="docutils literal"><span class="pre">parentGenerator()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">parents</span></tt></li>
</ul>
<p>So instead of this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">parent</span> <span class="ow">in</span> <span class="n">tag</span><span class="o">.</span><span class="n">parentGenerator</span><span class="p">():</span>
    <span class="o">...</span>
</pre></div>
</div>
<p>You can write this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">parent</span> <span class="ow">in</span> <span class="n">tag</span><span class="o">.</span><span class="n">parents</span><span class="p">:</span>
    <span class="o">...</span>
</pre></div>
</div>
<p>(But the old code will still work.)</p>
<p>Some of the generators used to yield <tt class="docutils literal"><span class="pre">None</span></tt> after they were done, and
then stop. That was a bug. Now the generators just stop.</p>
<p>There are two new generators, <a class="reference internal" href="index.html#string-generators"><em>.strings and
.stripped_strings</em></a>. <tt class="docutils literal"><span class="pre">.strings</span></tt> yields
NavigableString objects, and <tt class="docutils literal"><span class="pre">.stripped_strings</span></tt> yields Python
strings that have had whitespace stripped.</p>
</div>
<div class="section" id="xml">
<h3>XML<a class="headerlink" href="index.html#xml" title="Permalink to this headline">¶</a></h3>
<p>There is no longer a <tt class="docutils literal"><span class="pre">BeautifulStoneSoup</span></tt> class for parsing XML. To
parse XML you pass in &#8220;xml&#8221; as the second argument to the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor. For the same reason, the
<tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor no longer recognizes the <tt class="docutils literal"><span class="pre">isHTML</span></tt>
argument.</p>
<p>Beautiful Soup&#8217;s handling of empty-element XML tags has been
improved. Previously when you parsed XML you had to explicitly say
which tags were considered empty-element tags. The <tt class="docutils literal"><span class="pre">selfClosingTags</span></tt>
argument to the constructor is no longer recognized. Instead,
Beautiful Soup considers any empty tag to be an empty-element tag. If
you add a child to an empty-element tag, it stops being an
empty-element tag.</p>
</div>
<div class="section" id="entities">
<h3>Entities<a class="headerlink" href="index.html#entities" title="Permalink to this headline">¶</a></h3>
<p>An incoming HTML or XML entity is always converted into the
corresponding Unicode character. Beautiful Soup 3 had a number of
overlapping ways of dealing with entities, which have been
removed. The <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor no longer recognizes the
<tt class="docutils literal"><span class="pre">smartQuotesTo</span></tt> or <tt class="docutils literal"><span class="pre">convertEntities</span></tt> arguments. (<a class="reference internal" href="index.html#unicode-dammit">Unicode,
Dammit</a> still has <tt class="docutils literal"><span class="pre">smart_quotes_to</span></tt>, but its default is now to turn
smart quotes into Unicode.) The constants <tt class="docutils literal"><span class="pre">HTML_ENTITIES</span></tt>,
<tt class="docutils literal"><span class="pre">XML_ENTITIES</span></tt>, and <tt class="docutils literal"><span class="pre">XHTML_ENTITIES</span></tt> have been removed, since they
configure a feature (transforming some but not all entities into
Unicode characters) that no longer exists.</p>
<p>If you want to turn Unicode characters back into HTML entities on
output, rather than turning them into UTF-8 characters, you need to
use an <a class="reference internal" href="index.html#output-formatters"><em>output formatter</em></a>.</p>
</div>
<div class="section" id="id19">
<h3>Miscellaneous<a class="headerlink" href="index.html#id19" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="index.html#string"><em>Tag.string</em></a> now operates recursively. If tag A
contains a single tag B and nothing else, then A.string is the same as
B.string. (Previously, it was None.)</p>
<p><a class="reference internal" href="index.html#multi-valued-attributes">Multi-valued attributes</a> like <tt class="docutils literal"><span class="pre">class</span></tt> have lists of strings as
their values, not strings. This may affect the way you search by CSS
class.</p>
<p>If you pass one of the <tt class="docutils literal"><span class="pre">find*</span></tt> methods both <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a> <cite>and</cite>
a tag-specific argument like <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id77"><em>name</em></a>, Beautiful Soup will
search for tags that match your tag-specific criteria and whose
<a class="reference internal" href="index.html#string"><em>Tag.string</em></a> matches your value for <a class="reference internal" href="http://www.crummy.com/software/BeautifulSoup/bs4/doc/index.cn.html#id79"><em>text</em></a>. It will <cite>not</cite> find the strings themselves. Previously,
Beautiful Soup ignored the tag-specific arguments and looked for
strings.</p>
<p>The <tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt> constructor no longer recognizes the
<cite>markupMassage</cite> argument. It&#8217;s now the parser&#8217;s responsibility to
handle markup correctly.</p>
<p>The rarely-used alternate parser classes like
<tt class="docutils literal"><span class="pre">ICantBelieveItsBeautifulSoup</span></tt> and <tt class="docutils literal"><span class="pre">BeautifulSOAP</span></tt> have been
removed. It&#8217;s now the parser&#8217;s decision how to handle ambiguous
markup.</p>
<p>The <tt class="docutils literal"><span class="pre">prettify()</span></tt> method now returns a Unicode string, not a bytestring.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html#">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="index.html#">Beautiful Soup Documentation</a><ul>
<li><a class="reference internal" href="index.html#getting-help">Getting help</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#quick-start">Quick Start</a></li>
<li><a class="reference internal" href="index.html#installing-beautiful-soup">Installing Beautiful Soup</a><ul>
<li><a class="reference internal" href="index.html#problems-after-installation">Problems after installation</a></li>
<li><a class="reference internal" href="index.html#installing-a-parser">Installing a parser</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#making-the-soup">Making the soup</a></li>
<li><a class="reference internal" href="index.html#kinds-of-objects">Kinds of objects</a><ul>
<li><a class="reference internal" href="index.html#tag"><tt class="docutils literal"><span class="pre">Tag</span></tt></a><ul>
<li><a class="reference internal" href="index.html#name">Name</a></li>
<li><a class="reference internal" href="index.html#attributes">Attributes</a><ul>
<li><a class="reference internal" href="index.html#multi-valued-attributes">Multi-valued attributes</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="index.html#navigablestring"><tt class="docutils literal"><span class="pre">NavigableString</span></tt></a></li>
<li><a class="reference internal" href="index.html#beautifulsoup"><tt class="docutils literal"><span class="pre">BeautifulSoup</span></tt></a></li>
<li><a class="reference internal" href="index.html#comments-and-other-special-strings">Comments and other special strings</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#navigating-the-tree">Navigating the tree</a><ul>
<li><a class="reference internal" href="index.html#going-down">Going down</a><ul>
<li><a class="reference internal" href="index.html#navigating-using-tag-names">Navigating using tag names</a></li>
<li><a class="reference internal" href="index.html#contents-and-children"><tt class="docutils literal"><span class="pre">.contents</span></tt> and <tt class="docutils literal"><span class="pre">.children</span></tt></a></li>
<li><a class="reference internal" href="index.html#descendants"><tt class="docutils literal"><span class="pre">.descendants</span></tt></a></li>
<li><a class="reference internal" href="index.html#string"><tt class="docutils literal"><span class="pre">.string</span></tt></a></li>
<li><a class="reference internal" href="index.html#strings-and-stripped-strings"><tt class="docutils literal"><span class="pre">.strings</span></tt> and <tt class="docutils literal"><span class="pre">stripped_strings</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#going-up">Going up</a><ul>
<li><a class="reference internal" href="index.html#parent"><tt class="docutils literal"><span class="pre">.parent</span></tt></a></li>
<li><a class="reference internal" href="index.html#parents"><tt class="docutils literal"><span class="pre">.parents</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#going-sideways">Going sideways</a><ul>
<li><a class="reference internal" href="index.html#next-sibling-and-previous-sibling"><tt class="docutils literal"><span class="pre">.next_sibling</span></tt> and <tt class="docutils literal"><span class="pre">.previous_sibling</span></tt></a></li>
<li><a class="reference internal" href="index.html#next-siblings-and-previous-siblings"><tt class="docutils literal"><span class="pre">.next_siblings</span></tt> and <tt class="docutils literal"><span class="pre">.previous_siblings</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#going-back-and-forth">Going back and forth</a><ul>
<li><a class="reference internal" href="index.html#next-element-and-previous-element"><tt class="docutils literal"><span class="pre">.next_element</span></tt> and <tt class="docutils literal"><span class="pre">.previous_element</span></tt></a></li>
<li><a class="reference internal" href="index.html#next-elements-and-previous-elements"><tt class="docutils literal"><span class="pre">.next_elements</span></tt> and <tt class="docutils literal"><span class="pre">.previous_elements</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="index.html#searching-the-tree">Searching the tree</a><ul>
<li><a class="reference internal" href="index.html#kinds-of-filters">Kinds of filters</a><ul>
<li><a class="reference internal" href="index.html#a-string">A string</a></li>
<li><a class="reference internal" href="index.html#a-regular-expression">A regular expression</a></li>
<li><a class="reference internal" href="index.html#a-list">A list</a></li>
<li><a class="reference internal" href="index.html#true"><tt class="docutils literal"><span class="pre">True</span></tt></a></li>
<li><a class="reference internal" href="index.html#a-function">A function</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#find-all"><tt class="docutils literal"><span class="pre">find_all()</span></tt></a><ul>
<li><a class="reference internal" href="index.html#the-name-argument">The <tt class="docutils literal"><span class="pre">name</span></tt> argument</a></li>
<li><a class="reference internal" href="index.html#the-keyword-arguments">The keyword arguments</a></li>
<li><a class="reference internal" href="index.html#searching-by-css-class">Searching by CSS class</a></li>
<li><a class="reference internal" href="index.html#the-text-argument">The <tt class="docutils literal"><span class="pre">text</span></tt> argument</a></li>
<li><a class="reference internal" href="index.html#the-limit-argument">The <tt class="docutils literal"><span class="pre">limit</span></tt> argument</a></li>
<li><a class="reference internal" href="index.html#the-recursive-argument">The <tt class="docutils literal"><span class="pre">recursive</span></tt> argument</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#calling-a-tag-is-like-calling-find-all">Calling a tag is like calling <tt class="docutils literal"><span class="pre">find_all()</span></tt></a></li>
<li><a class="reference internal" href="index.html#find"><tt class="docutils literal"><span class="pre">find()</span></tt></a></li>
<li><a class="reference internal" href="index.html#find-parents-and-find-parent"><tt class="docutils literal"><span class="pre">find_parents()</span></tt> and <tt class="docutils literal"><span class="pre">find_parent()</span></tt></a></li>
<li><a class="reference internal" href="index.html#find-next-siblings-and-find-next-sibling"><tt class="docutils literal"><span class="pre">find_next_siblings()</span></tt> and <tt class="docutils literal"><span class="pre">find_next_sibling()</span></tt></a></li>
<li><a class="reference internal" href="index.html#find-previous-siblings-and-find-previous-sibling"><tt class="docutils literal"><span class="pre">find_previous_siblings()</span></tt> and <tt class="docutils literal"><span class="pre">find_previous_sibling()</span></tt></a></li>
<li><a class="reference internal" href="index.html#find-all-next-and-find-next"><tt class="docutils literal"><span class="pre">find_all_next()</span></tt> and <tt class="docutils literal"><span class="pre">find_next()</span></tt></a></li>
<li><a class="reference internal" href="index.html#find-all-previous-and-find-previous"><tt class="docutils literal"><span class="pre">find_all_previous()</span></tt> and <tt class="docutils literal"><span class="pre">find_previous()</span></tt></a></li>
<li><a class="reference internal" href="index.html#css-selectors">CSS selectors</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#modifying-the-tree">Modifying the tree</a><ul>
<li><a class="reference internal" href="index.html#changing-tag-names-and-attributes">Changing tag names and attributes</a></li>
<li><a class="reference internal" href="index.html#modifying-string">Modifying <tt class="docutils literal"><span class="pre">.string</span></tt></a></li>
<li><a class="reference internal" href="index.html#append"><tt class="docutils literal"><span class="pre">append()</span></tt></a></li>
<li><a class="reference internal" href="index.html#beautifulsoup-new-string-and-new-tag"><tt class="docutils literal"><span class="pre">BeautifulSoup.new_string()</span></tt> and <tt class="docutils literal"><span class="pre">.new_tag()</span></tt></a></li>
<li><a class="reference internal" href="index.html#insert"><tt class="docutils literal"><span class="pre">insert()</span></tt></a></li>
<li><a class="reference internal" href="index.html#insert-before-and-insert-after"><tt class="docutils literal"><span class="pre">insert_before()</span></tt> and <tt class="docutils literal"><span class="pre">insert_after()</span></tt></a></li>
<li><a class="reference internal" href="index.html#clear"><tt class="docutils literal"><span class="pre">clear()</span></tt></a></li>
<li><a class="reference internal" href="index.html#extract"><tt class="docutils literal"><span class="pre">extract()</span></tt></a></li>
<li><a class="reference internal" href="index.html#decompose"><tt class="docutils literal"><span class="pre">decompose()</span></tt></a></li>
<li><a class="reference internal" href="index.html#replace-with"><tt class="docutils literal"><span class="pre">replace_with()</span></tt></a></li>
<li><a class="reference internal" href="index.html#wrap"><tt class="docutils literal"><span class="pre">wrap()</span></tt></a></li>
<li><a class="reference internal" href="index.html#unwrap"><tt class="docutils literal"><span class="pre">unwrap()</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#output">Output</a><ul>
<li><a class="reference internal" href="index.html#pretty-printing">Pretty-printing</a></li>
<li><a class="reference internal" href="index.html#non-pretty-printing">Non-pretty printing</a></li>
<li><a class="reference internal" href="index.html#output-formatters">Output formatters</a></li>
<li><a class="reference internal" href="index.html#get-text"><tt class="docutils literal"><span class="pre">get_text()</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#specifying-the-parser-to-use">Specifying the parser to use</a><ul>
<li><a class="reference internal" href="index.html#differences-between-parsers">Differences between parsers</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#encodings">Encodings</a><ul>
<li><a class="reference internal" href="index.html#output-encoding">Output encoding</a></li>
<li><a class="reference internal" href="index.html#unicode-dammit">Unicode, Dammit</a><ul>
<li><a class="reference internal" href="index.html#smart-quotes">Smart quotes</a></li>
<li><a class="reference internal" href="index.html#inconsistent-encodings">Inconsistent encodings</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="index.html#parsing-only-part-of-a-document">Parsing only part of a document</a><ul>
<li><a class="reference internal" href="index.html#soupstrainer"><tt class="docutils literal"><span class="pre">SoupStrainer</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="index.html#diagnose"><tt class="docutils literal"><span class="pre">diagnose()</span></tt></a></li>
<li><a class="reference internal" href="index.html#errors-when-parsing-a-document">Errors when parsing a document</a></li>
<li><a class="reference internal" href="index.html#version-mismatch-problems">Version mismatch problems</a></li>
<li><a class="reference internal" href="index.html#parsing-xml">Parsing XML</a></li>
<li><a class="reference internal" href="index.html#other-parser-problems">Other parser problems</a></li>
<li><a class="reference internal" href="index.html#miscellaneous">Miscellaneous</a></li>
<li><a class="reference internal" href="index.html#improving-performance">Improving Performance</a></li>
</ul>
</li>
<li><a class="reference internal" href="index.html#id18">Beautiful Soup 3</a><ul>
<li><a class="reference internal" href="index.html#porting-code-to-bs4">Porting code to BS4</a><ul>
<li><a class="reference internal" href="index.html#you-need-a-parser">You need a parser</a></li>
<li><a class="reference internal" href="index.html#method-names">Method names</a></li>
<li><a class="reference internal" href="index.html#generators">Generators</a></li>
<li><a class="reference internal" href="index.html#xml">XML</a></li>
<li><a class="reference internal" href="index.html#entities">Entities</a></li>
<li><a class="reference internal" href="index.html#id19">Miscellaneous</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/index.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li><a href="index.html#">Beautiful Soup 4.2.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2012, Leonard Richardson.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
    </div>
  </body>
</html>
